LimeSurvey Manual - User contributions [en]

RemoteControl

2010-08-05T09:21:04Z

Rakete:

__TOC__

=Introduction=

LimeSurvey RemoteControl is a PHP:SOAP based Web service application.

The LSRC makes it possible for developers to control specific functionality of Limesurvey from any other Application, without beeing restricted to PHP as a Programming language.

You can start a predefined survey (change titles and things), add predefined groups or questions to this coresurvey. Activate the survey, restrict it to start and endtime, make it closed, add Participant data or just tokens when you need them (your customer just bought a book and now you want to invite him to a closed survey automatically), return the unused tokens to the main application, delete a survey, get a fieldmap for a survey, invite or remind the participants of your survey, etc...

Be aware that this piece of code was originally written to bind LimeSurvey to a University management software in order to evaluate lectures. So there could be comments in the code or documentation, which have to do with my Company's Software or which are just a little bit confusing when you have nothing to do with University's or the German language.

Post any comments, wishes or bugs to the [http://bugs.limesurvey.org bugtracker].

==Files included in LSRC==
* lsrc.config.php (configuration variables)
* lsrc.server.php (the logical SOAP:Server brain. Programm logic is mainly in here )
* lsrc.helper.php (class LsrcHelper, this Class does the work. Mainly copied and customized from Limesurvey files. Especially for import tasks)
* lsrc_orig.wsdl (wsdl definition for SOAP messages. From this file the lsrc.wsdl is generated with correct paths)
* lsrc.testclient.php (to test the environment and functionality of the webservice on the fly)

== Directory included==
* \surveys (for the core survey .csv's.) Used by sCreateSurvey.
* \groups (for exported group .csv's . Used by sImportGroup. There should be always an empty group for importing, so you can add questions to a new group)
* \questions (for exported questions .csv's. sImportFreetext and sImportMatrix depend on "Freitext.csv" and "Matrix5.csv" which should be exported questions(Freetext and Array 5 point Matrix).

== Requirements==
* PHP >= 5.2.1 with PHP:SOAP Extension enabled
* libXML installed
* MySQL, PostgreSQL or (not recommended) MSSQL
* (optional) OpenSSL
* (optional) a Certificate for better Security

==Known issues (and workarounds)==
* PHP 5.3.0 has a bug ([http://bugs.php.net/bug.php?id=49014 here] and [http://bugs.php.net/bug.php?id=49094 here]) which prevents createding/reading wsdl files. We strongly recommend to update to a later PHP version.
* Surveys get not imported in 1.85, due to a bug. The bug is fixed and will be released with the next release. Talk to rakete if you need it earlier...
* exported csv's prior 1.81 will not import over lsrc anymore. Import them via Browser and export them back to lsrc to get them work again. (attributes moved from survey to survey_languagesettings)
* sInsertPaticipants and sInsertToken function: You should note, that in case of an Seperator at the beginning or the end of the Datastring, the return Message will recognize one more given Dataset or Token as inserted into the db...
* There is a bug with Webservices in general: Sometimes (~ 1 of 10.000 Cases) you will get an error message like "function 'anyFunction' does not exist on the server" or similar, altough everything is fine. Just wait a few Moments, clear you cache, phone your mom (she will be happy to hear from you ;)) and try again.
* Webservice will not work if the "install" dir is not renamed or deleted in limesurvey and $debug is not set to 2 -> "looks like we got no xml document" without errorlogs

Please add your bug report to the [http://bugs.limesurvey.org bugtracker] if you found an Issue that is not listed here.

=Setup=

== How to configure LSRC==

In a default LimeSurvey installation LSRC is disabled. In order to use LSRC you must first enable the service, and then adjust the settings to suit your needs.
* To '''enable the LSRC in LimeSurveys config.php''' or in lsrc.config.php
** set the variable '''$enableLsrc = true''';
* In the '''lsrc.config.php''' file, you can '''set all needed Variables''' for the LSRC in Section Variables.
** set the Error Handling. While configuring and testing it is very good to get all errors. If you are using lsrc in Production, you should comment error_reporting, so that it sticks to the servers defaults.
** $lsrcDebug, if set to true, the lsrc writes it's own log. This log is particularly helpful when implementing new features. If some functions of LSRC don't work look for where it stops functioning in this log. Once you have finished setting up or developing new features you should turn the log off by setting this value to false.
** $lsrcDebugLog, The name of the file where the log should be written.
** ini_set("log_errors", "1"), Apaches log file (error.log) will get filed with php-errors. Very useful for debugging. Comment this line out (put two forward slashes at the beginning of the line "//") once you have finished setting up and have put your LSRC service into production.
** ini_set("soap.wsdl_cache_enabled", "0"), while testing, caching is not useful. If in productive Mode, turn this on or just comment the line to stick to server defaults.
** (optional) set $lsrcOverSSL to true, if you want SOAP to exchange the messages over SSL resp. https. '''Note:'''Turning this on simply changes the internal addressing to either "https:" or "http:" in order to work over a SSL connection, nothing more.
** set the directories, where the .csv files to import can be found. You will have to export some survey, you want to import and activate with LSRC, first.
** (optional) change $sLsrcSeparator = "your separator"; in lsrc.config.php if you wish to separate tokens for the sInsertToken function with any other separator than default, which is a comma.
** (optional) change $sDatasetSeperator= "your separator"; in lsrc.config.php if you wish to separate Datasets for the sInsertParticipants function with any other separator than default, which are two colons.
** (optional) change $sDatafieldSeperator= "your separator"; in lsrc.config.php if you wish to separate Datafields for the sInsertParticipants function with any other separator than default, which is a semicolon.
** (optional) set $export4lsrc = true; if you want to export surveys, groups and questions to remotecontrol folders for importing remotely. They must be writeable.
* the script needs rights to write files to the folder "admin/remotecontrol/" (lsrc.log, if logging is used and lsrc.wsdl). if(you cannot or don't want to set the directory rights to 777){create those two files(lsrc.log and lsrc.wsdl)in the lsrc dir with the permission to write them(777))
* If you want to save Survey, group or question csv's directly from Limesurvey into the lsrc Folders, you need to set them to 777, too. (Option can be enabled by adding $export4lsrc = true; to Limesurveys config.php)
* You may have to generate a wsdl file if you need a static one. Run lsrc.server.php?wsdl and the script will make a lsrc.wsdl with the correct server url included in the lsrc directory.
* If auto wsdl generation do not work properly (maybe virtual hosts make Problems, please report back, if so or not so, can't test at the moment) You have to set the url of the lsrc.server.php script in the last block of the wsdl

==How to enable OpenSSL / https Support==
* LSRC supports SSL over http resp. https.
* Your Webserver needs to support and enable OpenSSL (See your Webserver Manual)
* '''ATTENTION:''' Just set the Variable $lsrcOverSSL = true; in lsrc.config.php. After that, initialize your client like shown below, a wsdl file with correct URL will be generated automaticly for you:

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

new SoapClient('https://localhost/limesurvey/admin/lsrc.server.php?wsdl',

array('soap_version' => SOAP_1_1,

'trace' => 1));

</syntaxhighlight>
* 'ONLY FOLLOW THIS STEPS IF WSDL GENERATION DOES NOT WORK FOR YOU' <br>There are two locations in the code, where you force the webservice to use https

<nowiki>:</nowiki> 1. On the client side, when you call the SOAP-Server over wsdl. For 'https' do it like that:

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

new SoapClient('https://localhost/limesurvey/admin/remotecontrol/lsrc.wsdl', array('soap_version' => SOAP_1_1,

'trace' => 1));

</syntaxhighlight>

<nowiki>:</nowiki> for 'http' like that:

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

new SoapClient('http://localhost/limesurvey/admin/remotecontrol/lsrc.wsdl', array('soap_version' => SOAP_1_1,

'trace' => 1));

</syntaxhighlight>

<nowiki>:</nowiki> Note that the client will only get the wsdl-definition over https, to get the SOAP Messages over https, set the uri in the wsdl file, like below...

<nowiki>:</nowiki> 2. Here is the most important Step to SSL. At the End of the lsrc.wsdl file, last block, same procedure:

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

<port name='LsrcPort' binding='tns:LsrcBinding'>

<soap:address location='https://localhost/limesurvey/admin/remotecontrol/lsrc.server.php' />

</port>

</syntaxhighlight>

<nowiki>:</nowiki> or for normal http mode:

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

<port name='LsrcPort' binding='tns:LsrcBinding'>

<soap:address location='http://localhost/limesurvey/admin/remotecontrol/lsrc.server.php' />

</port>

</syntaxhighlight>

That's it! all request, response and fault messages will be transported over https...

=How to use LSRC=

==use the client==

'''NOTE on PHP 5.3:''' setting the path2wsdl to http://localhost/limesurvey/admin/remotecontrol/lsrc.server.php?wsdl worked with all prior 5.3 version of PHP. With PHP 5.3 the client will not recognize the wsdl lsrc.server.php?wsdl gives back. You have to call lsrc.server.php?wsdl once to generate the lsrc.wsdl file and then point your client to http://localhost/limesurvey/admin/remotecontrol/lsrc.wsdl instead.

There is a PHPclient (from version 1.86) in the remotecontrol folder. You can use this ClientClass to control Limesurvey from within your PHP Applications with ease.

Take a look at lsrc.testclient-new.php to get an impression of how it can be implemented.

Basically you just have to include the class, prepare the Client and start the function calls.

Example:

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

<?php

/**
* include the client class
*/

include_once("lsrc.client.php");

/**
* initiate the testclient object
*/

$testclient = new lsrcClient();

/**
* prepare the lsrcClient class (initiate the soapClient, set sid if needed)
*/

$testclient->prepare(333);

/**
* set user and password (only needed, when not set in the client class directly)
*/

$testclient->user = 'admin';

$testclient->pass = 'password';

/**
* set the path2wsdl (only needed, when not set in the client class directly)
*/

$testclient->path2wsdl = 'http://localhost/limesurvey/admin/remotecontrol/lsrc.server.php?wsdl';

/**
* call the function to create a survey
*/

$sReturn = $testclient->createSurvey("surveyName" ,

"surveyDescription",

"welcomeText",

"endText",

"surveyAdmins@email.adress",

"Survey Adminsname",

"http://an.end.url",

"Description of End Url",

"template138");

echo $sReturn;

</syntaxhighlight>

This Skript initiates the client. The parameter at prepare, sets the surveyId. In this case it means we are going to create the survey with the Id 333. If you do not give an id, the survey will get a random id.

Next we set the user and password to use. You do not have to do this, as long as the inital values of the client are correct. But you may have to, if you build your app in a way, that different users use the client to create Surveys or edit them.

In the end, the survey is created with the createSurvey Method and the return is echoed.

==using the functions==

You will need a SOAP- or at least RPC-Client to communicate with the LSRC Webservice. How to create such a Client depends on the programming language you use.

The LSRC itself is written in PHP5 using the PHP:SOAP extension with SOAP 1.1.

In PHP you would initiate the Client-object and call a function from the Webservice with code like e.g.:

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

$wsdl="http://localhost/limesurvey/admin/remotecontrol/lsrc.server.php?wsdl";

$client = new SoapClient($wsdl, array('soap_version' => SOAP_1_1,

'trace' => 1));

try

{

$sReturn = $client->sInsertToken($user, $pass, $iVid, $sToken);

}

catch (SoapFault $fault)

{

$sOutput .= " <br/><br/>SOAP Error: ".$fault->faultcode." : ".$fault->faultstring;

}

</syntaxhighlight>

The LSRC offers some functions:

(<span style='color:#FF0000'>m</span>) means: Mandatory Parameter

==sCreateSurvey==

<span style='color:#FF0000'>Parameters changed after 1.81+! (sVend added)</span>
* String sCreateSurvey($sUser, $sPass, $iVid, $sVtit , $sVbes, $sVwel, $sVend, $sMail, $sName, $sUrl, $sUbes, $sVtyp )
** '''Purpose''': Creates a new survey. It imports an exported survey from any LS v1.xx. and changes some fields (in the current Version it changes SurveyTitle, SurveyDescription and SurveyWelcomeText, adminemail, adminname, url and url_description to the string which was given by the client.)
** '''Parameters''':
*** (<span style='color:#FF0000'>m</span>) string USER, this have to be an existing Useraccount with appropriate rights
*** (<span style='color:#FF0000'>m</span>) string PASSWORD, this has to match the password for the account.
*** (<span style='color:#FF0000'>m</span>) int $iVid, SurveyID desired ID for the Survey, make sure it doesn't already exist in LimeSurvey
*** (<span style='color:#FF0000'>m</span>) string $sVtit, SurveyTitle, should be the (Nr +)Name of the Event to be evaluated
*** (<span style='color:#FF0000'>m</span>) string $sVbes, Survey Description, This should be String put together with veransttyp + doztitle + dozname
*** string $sVwel, Survey Welcometext, A text shown before the survey starts. If not given it says: "Herzlich Willkommen zur Evaluation von "$sVtit"
*** string $sVend, Survey Endtext, Text shown at the endpage.
*** string $sMail, Admin Email, Email Adress of the responsible person for this survey
*** string $sName, Name of the responsible person for this survey
*** string $sUrl, Url of the Link, shown on the last page of survey.
*** string $sUbes, Description String of the URL above. ( <a href='$sUrl'>$sUbes</a> )
*** string $sVtyp, The type of Event that should be evaluated. Use in combination with sAvailableModules with $mode='core' to get all available "types"
** '''Returns''':
*** if everything went fine, it returns the SurveyID from the created survey
** '''Possible Faults''':
*** throw new SoapFault("Authentication: ", "User or password wrong");
*** throw new SoapFault("Database: ", "SurveyID already exists");
*** throw new SoapFault("Server: ", "Mandatory Parameters missing");
*** throw new SoapFault("Server: ", "Import went wrong somehow");
** '''Note''':
*** Goto line 714 in lsrc.helper.php to see what can be done and customized while importing.
*** If you want Limesurvey to give your Survey a random Number if the given ID exist (because you do not need a specific identification for your surveys), just go into the function sCreateSurvey in lsrc.server.php and delete or comment out the if($lsrcHelper->surveyExists($iVid)) clause. In Result, Limesurvey will give your survey a random ID when the given ID exists.

==sActivateSurvey==
* String '''sActivateSurvey'''(string USER, string PASSWORD, int SurveyID, date start, date end)
** '''Purpose''': Activates an existing survey and set start and enddate optional
** '''Parameters''':
*** (<span style='color:#FF0000'>m</span>) string USER, this have to be an existing Useraccount with appropriate rights
*** (<span style='color:#FF0000'>m</span>) string PASSWORD, this has to match the password for the account.
*** (<span style='color:#FF0000'>m</span>) int SurveyID, the SurveyID for the Survey to activate.
*** date start, date for the Survey to start. 2008-10-22 means it starts exactly at 2008-10-22 00:00:00 Servertime
*** date end, date for the Survey to end. 2008-10-22 means it ends exactly at 2008-10-22 23:59:59 Servertime. Nobody can access nor complete the Survey only a second later.
** '''Returns''':
*** if everything went fine, it returns the SurveyID from the activated survey
** '''Possible Faults''':
*** throw new SoapFault("Authentication: ", "User or password wrong");
*** throw new SoapFault("Database: ", "Survey you want to activate does not exists");
*** throw new SoapFault("Server: ", "Mandatory Parameters missing");
*** throw new SoapFault("Server: ", "Activation went wrong somehow");
** '''Note''':
*** You can set startDate and/or endDate after activation if needed. Just run the function again with desired parameters.

==sImportGroup==
* String '''sImportGroup'''(string USER, string PASSWORD, int SurveyID, String Module, String groupName, String groupDescription)
** '''Purpose''': Imports an exported group file (.csv) to the Survey given by SurveyID
** '''Parameters''':
*** (<span style='color:#FF0000'>m</span>) string USER, this have to be an existing Useraccount with appropriate rights
*** (<span style='color:#FF0000'>m</span>) string PASSWORD, this has to match the password for the account.
*** (<span style='color:#FF0000'>m</span>) int SurveyID, the SurveyID
*** (<span style='color:#FF0000'>m</span>) string Module, the filename of the Group you want to add to the Survey. Use sAvailableModules to get the available groups.
*** string groupName, the Title the Group gets. If not set, it will use the title given in the .csv.
*** string groupDescription, Description of the group. If not set, it will use the description given in the .csv.
** '''Returns''':
*** if everything went fine, it returns the String "Import OK"
** '''Possible Faults''':
*** throw new SoapFault("Authentication: ", "User or password wrong");
*** throw new SoapFault("Authentication: ", "You have no right to change Surveys from other people");
*** throw new SoapFault("Server: ", "Survey Module $sMod does not exist");
*** throw new SoapFault("Server: ", "Group does not support Surveys Baselanguage ($langcode)");
** '''Note''':
*** It imports only exported groups as .csv which lay under \groups or any other dir given in lsrc.config.php
*** <strike>It imports only the files beginning with "mod_" ending with ".csv"</strike>
*** The Param Module must only contain the "name of the Module": Only the String before ".csv"
*** The baselanguage of the group to import, have to match the baselanguage of the coresurvey.

==sImportQuestion==
* String '''sImportQuestion'''(string USER, string PASSWORD, int SurveyID, String Module, String mandatory)
** '''Purpose''': Imports an exported question file (.csv) to the last group of the Survey given by SurveyID. This is meant for predefined questions stored in the /question directory
** '''Parameters''':
*** (<span style='color:#FF0000'>m</span>) string USER, this have to be an existing Useraccount with appropriate rights
*** (<span style='color:#FF0000'>m</span>) string PASSWORD, this has to match the password for the account.
*** (<span style='color:#FF0000'>m</span>) int SurveyID, the SurveyID
*** (<span style='color:#FF0000'>m</span>) String Module, the name of the csv file you want to add to the Survey, without extension(.csv).
*** String mandatory, default='N' set to 'Y' if you want that question mandatory
** '''Returns''':
*** if everything went fine, it returns the String "OK"
** '''Possible Faults''':
*** throw new SoapFault("Authentication: ", "User or password wrong");
*** throw new SoapFault("Authentication: ", "You have no right to change Surveys from other people");
*** throw new SoapFault("Server: ", "Group does not support Surveys Baselanguage ($langcode)");
** '''Note''':
*** It imports only exported questions as .csv which lay under \questions or any dir given in lsrc.config.php
*** The baselanguage of the question to import, have to match the baselanguage of the core survey.

==sImportFreetext==
* String '''sImportFreetext'''(string USER, string PASSWORD, int SurveyID, String questionTitle, String questionText, String questionhelp, String module='freitext', string mandatory)
** '''Purpose''': Imports an exported question file (.csv) to the last Group of the survey given by SurveyID and changes the Title, question and helptext. This is meant for importing empty question.csv's (Text Questions)
** '''Parameters''':
*** (<span style='color:#FF0000'>m</span>) string USER, this have to be an existing Useraccount with appropriate rights
*** (<span style='color:#FF0000'>m</span>) string PASSWORD, this has to match the password for the account.
*** (<span style='color:#FF0000'>m</span>) int SurveyID, the SurveyID
*** String questionTitle, Name or Categorie of the Question
*** String questionText, The Question itself
*** String questionhelp, A little Help text for better understanding of the Question
*** String module, the name of the Module you want to add to the Survey. It should be "Freitext" by default.
*** String mandatory, make the question mandatory by giving 'Y' as this param.
** '''Returns''':
*** if everything went fine, it returns the String "OK"
** '''Possible Faults''':
*** throw new SoapFault("Authentication: ", "User or password wrong");
*** throw new SoapFault("Authentication: ", "You have no right to change Surveys from other people");
*** throw new SoapFault("Server: ", "Group does not support Surveys Baselanguage ($langcode)");
** '''Note''':
*** It imports only exported questions as .csv which lay under \questions or any dir given in lsrc.config.php
*** It is meant for importing one shortext, Longtext or Hugetext Question and changing the Question and Helptext.
*** The baselanguage of the question to import, have to match the baselanguage of the core survey.
*** Be sure to have at least one proper .csv (Freitext.csv) in the proper directory (questions), to use this function.
*** Use sAvailableModules with mode='que' to get all question .csv's available.

==sImportMatrix==
* String '''sImportMatrix'''(string USER, string PASSWORD, int SurveyID, String Module, String questionText, String questionhelp, String questionItems)
** '''Purpose''': Imports an exported question file (Matrix5.csv) to the Survey given by SurveyID and changes the question, helptext and gives Items to the 5 Scale Matrix. This is meant for importing one 5 Scale Matrix Question.
** '''Parameters''':
*** (<span style='color:#FF0000'>m</span>) string USER, this have to be an existing Useraccount with appropriate rights
*** (<span style='color:#FF0000'>m</span>) string PASSWORD, this has to match the password for the account.
*** (<span style='color:#FF0000'>m</span>) int SurveyID, the SurveyID
*** string Module, the name of the Module you want to add to the Survey. It should be "Matrix" by default.
*** String questionText, the question or text to the Matrix
*** String questionhelp, the help text
*** String questionItems, the Items that should be rated, separated by commas
** '''Returns''':
*** if everything went fine, it returns the String "OK"
** '''Possible Faults''':
*** throw new SoapFault("Authentication: ", "User or password wrong");
*** throw new SoapFault("Server: ", "Group does not support Surveys Baselanguage ($langcode)");
** '''Note''':
*** It imports only exported groups as .csv which lay under docs\demosurveys\studiply_mod
*** It is meant for importing a group with only one 5 Scale Matrix Question and changing the Question and Helptext and add Items.
*** Be sure to use an user with the surveys baselanguage as default, because this language is used to fill the language fields for answers and questions while importing.

==sAvailableModules==
* String '''sAvailableModules'''(string USER, string PASSWORD, string mode)
** '''Purpose''': Returning all the csv Names of the csv's in the Directorys configured in lsrc.config.php
** '''Parameters''':
*** (<span style='color:#FF0000'>m</span>) string USER, this have to be an existing Useraccount with appropriate rights
*** (<span style='color:#FF0000'>m</span>) string PASSWORD, this has to match the password for the account.
*** String mode, (optional) "mod" for the available groups, "core" for the coreSurveys, "que" for addable questions. Default, when not given is "mod".
** '''Returns''':
*** if everything went fine, it returns a String with all surveys, groups or questions (depends on mode) in the Dir given in lsrc.config.php, separated by comma.
** '''Possible Faults''':
*** throw new SoapFault("Authentication: ", "User or password wrong");
** '''Note''':

==sSendEmail==
* String sSendEmail($sUser, $sPass, $surveyID, $type, $maxLsrcEmails='', $subject='', $emailText='')
** '''Purpose''': sends Emails to Participants of a particular survey
** '''Parameters''':
*** (<span style='color:#FF0000'>m</span>) string USER, this have to be an existing Useraccount with appropriate rights
*** (<span style='color:#FF0000'>m</span>) string PASSWORD, this has to match the password for the account.
*** (<span style='color:#FF0000'>m</span>) int surveyID, Id of the survey from which participants will be mailed
*** (<span style='color:#FF0000'>m</span>) string type, the kind of email you like to send (invite, remind or custom)
*** int $maxLsrcEmails, if you want to override $maxemails setting in config.php for sending mails with lsrc: here you go.
*** string subject, only needed if type==custom, the subject for the mail to be send.
*** string emailText, only needed if type==custom, the text for the mail to be send.
** '''Returns''':
*** "X Mails send" or "No Mails to send" in custom mode.
*** "X Mails send. X Mails left to send" or "No Mails to send" in invite mode.
*** "X Reminders send. X Reminders left to send" or "No Reminders to send" in remind mode.
** '''Possible Faults''':
*** throw new SoapFault("Authentication: ", "User or password wrong");
*** throw new SoapFault("Server: ", "Mandatory Parameters missing");
*** throw new SoapFault("Type: ", "Wrong send Type given. Possible types are: custom, invite or remind");
** '''Note''':
*** invite: When $maxemails is set the function sends only $maxemails in one go. If you call it again, it will go on to send the invitations, until everyone is invited.
*** remind: When $maxemails is set, it will only send $maxemails in one go. It checks if reminders have been send to other participants and if there are participants who received less reminders than others, the script will first send reminders to those who have not been reminded so often, until the remindercount is equal.
*** custom: $maxemails have no effect in custom mode. I have no solution for counting those who have been mailed before.

==sInsertToken==
* String '''sInsertToken'''(string USER, string PASSWORD, int SurveyID, string Token)
** '''Purpose''': Creates and populates a table {dbprefix}token_{SurveyID} and thus "closes" the survey. It is possible to add tokens to the existing table.
** '''Parameters''':
*** (<span style='color:#FF0000'>m</span>) int SurveyID, ID of the survey to close with a token table
*** string Token, a string with comma separated tokens. There is a possibility to set any other separator in config.php. Max. tested length of a string was 500,000 tokens, that makes a String of 5,500,000 Chars, this is just the limit of the apache webserver on my notebook (CoreDuo 1,6MHz, 1GB Ram) with default Resource Limits (60,60,16). I recommend to send max. 100,000 tokens over the webservice. Repeat for more tokens.
*** (<span style='color:#FF0000'>m</span>) string USER, this have to be an existing Admin-, Superadmin- or Useraccount with the rights to create and activate Surveys
*** (<span style='color:#FF0000'>m</span>) string PASSWORD, this has to match the password for the account.
** '''Returns''':
*** if everything went ok, it returns the String: "[X] Token given, [X] Token inserted"
** '''Possible Faults''':
*** throw new SoapFault("Authentication: ", "User or password wrong");
*** throw new SoapFault("Database: ", "Survey does not exists");
*** throw new SoapFault("Server: ", "Token could not be inserted");
** '''Note''':
*** Make sure on the client side that no token appears twice in the table. There is no check on this and won't be in the future. What happens if there are two same tokens? 2 participants will get the same token, one will fill out the form for both, and the other will get a message: "your token have already participated"
*** If there is no token table, it will create one and add the tokens.
*** If the Tokentable already exists, it just adds the given tokens to the existing table.

==sInsertParticipants==
* String '''sInsertParticipants'''(string USER, string PASSWORD, int SurveyID, string ParticipantData)
** '''Purpose''': Creates and populates a table {dbprefix}token_{SurveyID} and thus "closes" the survey. You can deliver some data to the token table. If you do not support a token, or an empty String as token, a unique token will be generated for the participant.
** '''Parameters''':
*** (<span style='color:#FF0000'>m</span>) int SurveyID, ID of the survey to close with a token table
*** string ParticipantData, The Data have to be in the right Syntax, it's like this:

<pre>

FIRSTNAME;LASTNAME;EMAIL;ATTRIB1;ATTRIB2;TOKEN::FIRSTNAME;LASTNAME;EMAIL;ATTRIB1;ATTRIB2;TOKEN

</pre>

'''NOTE: The Data Syntax change with 1.86'''. in order to take language, validfrom, validuntil and a variable count of attributes.

With 1.86 and later versions, it will have to be like this:

<pre>

FIRSTNAME;LASTNAME;EMAIL;LANGUAGE;TOKEN;VALIDFROM;VALIDUNTIL;attribute1,attribute2,attribute3::FIRSTNAME ... etc.

</pre>

note that the 8th field is the attributes field. There is no 9th field. You can seperate many attributes with a colon (,). The lsrc will create the needed fields in the db if they are not present. All Fields after LANGUAGE are optional and do not have to be send.

seperate the Datasets with double colons (::) and the fields with semicolon (;). The '''attrib1, attrib2 and token fields are optional''', you can just leave them out if not used. Note that the attrib field will get empty and not NULL, by now there where no complications, inform us, if you see some difficulties in not setting them NULL. Max. successfully tested length of a string was 3,000,000 Chars, this is just the limit of the apache webserver on my notebook (CoreDuo 1,6MHz, 1GB Ram) with default Resource Limits (60,60,16). I recommend to send max. 10,000 Datasets over the webservice at once(~1,000,000 chars). Repeat for more Datasets.
*** (<span style='color:#FF0000'>m</span>) string USER, this have to be an existing Admin-, Superadmin- or Useraccount with the rights to create and activate Surveys
*** (<span style='color:#FF0000'>m</span>) string PASSWORD, this has to match the password for the account.
** '''Returns''':
*** if everything went ok, it returns the String: "[X] Datasets given, [X] rows inserted. ";
** '''Possible Faults''':
*** throw new SoapFault("Authentication: ", "User or password wrong");
*** throw new SoapFault("Server: ", "No SurveyId given");
*** throw new SoapFault("Database: ", "Survey does not exists");
** '''Note''':
*** default tokenlength is 5 chars, if you want to change the length, goto lsrc.server.php, line 441
*** If the token table does not exists, it will be created, and if it does, the data will be added.

==sTokenReturn==
* string return '''sTokenReturn'''(string USER, string PASSWORD, int SurveyID)
** '''Purpose''': Gives back all Tokens, which did not complete the Survey, in a String seperated by commas.
** '''Parameters''':
*** (<span style='color:#FF0000'>m</span>) int SurveyID, the ID for the Survey from which you want get the unused tokens
*** (<span style='color:#FF0000'>m</span>) string USER, this have to be an existing Admin-, Superadmin- or Useraccount with the rights to create and activate Surveys
*** (<span style='color:#FF0000'>m</span>) string PASSWORD, this has to match the password for the account.
** '''Returns''':
*** Returns a String, a string of all unused tokens seperated by comma.
** '''Possible Faults''':
*** throw new SoapFault("Authentication: ", "User or password wrong");
*** throw new SoapFault("Database: ", "Survey does not exists");
*** throw new SoapFault("Server: ", "No SurveyId given");
*** throw new SoapFault("Database: ", "Token table for this Survey does not exists");
*** throw new SoapFault("Database: ", "No unused Tokens found");

==sGetFieldmap==
* string return '''sGetFieldmap'''(string USER, string PASSWORD, int SurveyID)
** '''Purpose''': Gives back the fieldmap for the survey

for example:

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

"fieldname","type","sid","gid","qid","aid","title","question","group_name","lid","lid1"

"111X779X39801","F","111","779","3980","1","1","How do you feel?","Paticipant feelings","",""

"111X779X39802","M","111","779","3980","2","1a","Why do you feel like this?","Paticipant feelings","",""

[...]

</syntaxhighlight>
** '''Parameters''':
*** (<span style='color:#FF0000'>m</span>) int SurveyID, the ID for the Survey from which you want to get the Fieldmap.
*** (<span style='color:#FF0000'>m</span>) string USER, this have to be an existing Admin-, Superadmin- or Useraccount with the rights to create and activate Surveys
*** (<span style='color:#FF0000'>m</span>) string PASSWORD, this has to match the password for the account.
** '''Returns''':
*** Returns a String, a string of the fieldmap, seperated by comma and blanks
** '''Possible Faults''':
*** throw new SoapFault("Authentication: ", "User or password wrong");
*** throw new SoapFault("Authentication: ", "You have no right to get fieldmaps from other peoples Surveys");
*** throw new SoapFault("Database: ", "Survey does not exists");
*** throw new SoapFault("Server: ", "No SurveyId given");

==fSendStatistic==

<span style='color:#FF0000'>''(since 1.86)''</span>
* '''fSendStatistic'''(string USER, string PASSWORD, int SurveyID, string Email, string doctype, string graph)
** '''Purpose''': sends an Statistic File as Attachment
** '''Parameters'''
*** user: Limesurvey user
*** password: Limesurvey Password
*** surveyId: ID of the survey from which statistics should be generated
*** email: the adress to which the statistic file is send
*** doctype: pdf, xls or html. With pdf or xls, the recipient gets an attached file with a short notice. With html, he gets an html e-mail without attachments
*** graph: turn graph generation on or off. Works only with pdf generation. Use '1' as a string if you want to enable it
** '''returns'''
*** string: 'XLS send'
*** string: 'PDF send'
*** string: 'HTML send'
** '''possible Faults'''
*** throw new SoapFault("Server: ", "Mandatory Parameters missing");
*** throw new SoapFault("Authentication: ", "User or password wrong");
*** throw new SoapFault("Authentication: ", "You have no right to send statistics from other peoples Surveys");
*** throw new SoapFault("Database: ", "Survey does not exists");
*** throw new SoapFault("Mail System", "Mail could not be send! Check your E-Mail Settings.");

=Testing=

For testing purposes, we made a testclient in php. Therefore you need a webserver to run it. If you test on one machine you need nothing to do, you can go to http://localhost/limesurvey/admin/lsrc/lsrc.testclient.php in your browser to test the webservices functionality.

Of Course this is very boring, because the apache talks with himself (and thats not the primary matter of a webservice).

The Testclient have two purposes:

1. It checks the Server(the one the testclient is running on!) for the PHP:SOAP Extension and installed libXML version and gives feedback if the enviroment does support SOAP via PHP:SOAP. This is very useful to check your Server and your Client towards PHP:SOAP compatibility. In addition to this, it will check if the wsdl file you want to connect to exists, it does not validate the wsdl file.

2. You can test the functions of the webservice.

If you test the webservice in realistic enviroment (two machines) you have to customize three things
* the lsrc.testclient.php needs to be on the machine where the webservice is NOT running, but it needs a webserver... download xampp from apachefriends if you dont have one <strike>(caution for Linux Users: you have to compile PHP5 with SOAP and enable the extension, futhermore you have to install libXML2. Last thing can by done very easy via Synaptics or apt-get)</strike> xampp for Linux works well with SOAP and libXML from version 1.7.
* this Line:

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

$limeUrl='https://localhost/limesource/limesurvey';

</syntaxhighlight>

At the beginning of lsrc.client.php (used by lsrc.testclient.php) set the target Limesurvey Installation Dir. localhost for servername is always wrong in this testcase, 127.0.0.1, too.

'''NOTES''':
* The Testclient is configured to use "admin" "password" as authentication. If you want to test with another user or password you have to set this vars in lsrc.testclient.php ( lines 40 and 41)
* If you just get a blank page on the testclient, make sure the path to the wsdl is correct, and the var $enableLsrc is set to true in config.php or lsrc.config.php

=Notes=
* Security is enhanced: no action without permission (as good as Limesurveys Security itself --> very good)
* No headers or "Quick and Dirtys" anymore, no Scripts, just functions and a class.
* All configuration Variables are stored in lsrc.config.php by now
* There is a debug functionality, showing where the script runs through the code in an own log file. Use Apaches error.log in addition to find errors if you got any.
* LSRC is part of LimeSurvey, therefore it stands under GNU/GPL License v2 or later.
* SOAP Services and therefore LSRC only support UTF-8 charsets.
* LSRC works with AdoDB (MySql,Postgresql, MSSQL) .
* LSRC is tested, but under steady development, use on your own risk, test the functions before using them productively!

=Changes=

1.86
* new function fSendStatistics: to send statistics as attachment to an e-mail-address
* Datasyntax for sInsertParticipants changed in order to take validfrom, validuntil, language and a variable Set of attributes.

1.85
* Several improvements to stability.

1.82
* Added sVend Parameter to sCreateSurvey, to set the endtext
* sInsertParticipants takes a token in the dataset, however, if non is supported, it will be generated.
* a new variable $enableLsrc is introduced to enable the Lsrc only when it is used.
* a serious exploit has been fixed.

1.81
* Added sGetFieldmap function.
* The template.csv's changed.
* exported csv's prior 1.81 will not import over lsrc anymore. Import them via Browser and export them back to lsrc.

1.80 => 1.81
* Changed sImportGroup: imports '''all''' groups under $modDir, adds them to the survey. Not only the ones with mod_ as prefix. In addition, you can give Name and Description of the Group.
* New sImportQuestion: imports questions in $queDir and adds them to the last group
* New sImportFreetext: imports a Freetext question and changes the title and question to the Strings given. Previously, this function was called sImportQuestion.
* Changed sAvailableModules: type can be core, mod or que. "que" is new and gives back the names of all the questions available.
* New sSendEmail: send invitations, reminders and custom mails to participants of a survey over Limesurvey.

=ToDo / ToCome=
* <strike>sInsertParticipants should take a lang attribute for each participant</strike>

please add your feature requests to the [http://bugs.limesurvey.org bugtracker] if it is not listed here...

=Security=

There have been a security hole in the versions prior 1.82 (1.80RC2 to 1.81+). This leak could be used to compromise your webspace if it is weakly configured.

To minimise the risk of a security leak endanger your system, we disabled the lsrc by default with version 1.82 and you have to enable it explicity in your config.php.

Some things you can do to improve your security when using the lsrc:
* instead of setting the remotecontrol folder to 777, just create an empty file lsrc.wsdl with the rights 777
* disable the lsrc.log in lsrc.config.php
* Do not set the survey, groups, questions folders to 777 for saving lsrc templates directly within Limesurvey, instead, save the .csv on your local PC and upload them via ftp to the folders.
* delete lsrc.testclient.php, when in productive use. Lsrc.testclient.php could be used from unauthorized people to perform portscanning on other machines. The attacked webserver would be seeing your webserver as attacker, altough you did not perform any attack by yourself. This is not so serious, as this bahaviour of the testclient is not much valuable for any serious hacker.

RemoteControl

2010-08-03T19:40:03Z

Rakete:

__TOC__

=Introduction=

LimeSurvey RemoteControl is a PHP:SOAP based Web service application.

The LSRC makes it possible for developers to control specific functionality of Limesurvey from any other Application, without beeing restricted to PHP as a Programming language.

You can start a predefined survey (change titles and things), add predefined groups or questions to this coresurvey. Activate the survey, restrict it to start and endtime, make it closed, add Participant data or just tokens when you need them (your customer just bought a book and now you want to invite him to a closed survey automatically), return the unused tokens to the main application, delete a survey, get a fieldmap for a survey, invite or remind the participants of your survey, etc...

Be aware that this piece of code was originally written to bind LimeSurvey to a University management software in order to evaluate lectures. So there could be comments in the code or documentation, which have to do with my Company's Software or which are just a little bit confusing when you have nothing to do with University's or the German language.

Post any comments, wishes or bugs to the [http://bugs.limesurvey.org bugtracker].

==Files included in LSRC==
* lsrc.config.php (configuration variables)
* lsrc.server.php (the logical SOAP:Server brain. Programm logic is mainly in here )
* lsrc.helper.php (class LsrcHelper, this Class does the work. Mainly copied and customized from Limesurvey files. Especially for import tasks)
* lsrc_orig.wsdl (wsdl definition for SOAP messages. From this file the lsrc.wsdl is generated with correct paths)
* lsrc.testclient.php (to test the environment and functionality of the webservice on the fly)

== Directory included==
* \surveys (for the core survey .csv's.) Used by sCreateSurvey.
* \groups (for exported group .csv's . Used by sImportGroup. There should be always an empty group for importing, so you can add questions to a new group)
* \questions (for exported questions .csv's. sImportFreetext and sImportMatrix depend on "Freitext.csv" and "Matrix5.csv" which should be exported questions(Freetext and Array 5 point Matrix).

== Requirements==
* PHP >= 5.2.1 with PHP:SOAP Extension enabled
* libXML installed
* MySQL, PostgreSQL or (not recommended) MSSQL
* (optional) OpenSSL
* (optional) a Certificate for better Security

==Known issues (and workarounds)==
* PHP 5.3.0 has a bug ([http://bugs.php.net/bug.php?id=49014 here] and [http://bugs.php.net/bug.php?id=49094 here]) which prevents createding/reading wsdl files. We strongly recommend to update to a later PHP version.
* Surveys get not imported in 1.85, due to a bug. The bug is fixed and will be released with the next release. Talk to rakete if you need it earlier...
* exported csv's prior 1.81 will not import over lsrc anymore. Import them via Browser and export them back to lsrc to get them work again. (attributes moved from survey to survey_languagesettings)
* sInsertPaticipants and sInsertToken function: You should note, that in case of an Seperator at the beginning or the end of the Datastring, the return Message will recognize one more given Dataset or Token as inserted into the db...
* There is a bug with Webservices in general: Sometimes (~ 1 of 10.000 Cases) you will get an error message like "function 'anyFunction' does not exist on the server" or similar, altough everything is fine. Just wait a few Moments, clear you cache, phone your mom (she will be happy to hear from you ;)) and try again.
* Webservice will not work if the "install" dir is not renamed or deleted in limesurvey and $debug is not set to 2 -> "looks like we got no xml document" without errorlogs

Please add your bug report to the [http://bugs.limesurvey.org bugtracker] if you found an Issue that is not listed here.

=Setup=

== How to configure LSRC==

In a default LimeSurvey installation LSRC is disabled. In order to use LSRC you must first enable the service, and then adjust the settings to suit your needs.
* To '''enable the LSRC in LimeSurveys config.php''' or in lsrc.config.php
** set the variable '''$enableLsrc = true''';
* In the '''lsrc.config.php''' file, you can '''set all needed Variables''' for the LSRC in Section Variables.
** set the Error Handling. While configuring and testing it is very good to get all errors. If you are using lsrc in Production, you should comment error_reporting, so that it sticks to the servers defaults.
** $lsrcDebug, if set to true, the lsrc writes it's own log. This log is particularly helpful when implementing new features. If some functions of LSRC don't work look for where it stops functioning in this log. Once you have finished setting up or developing new features you should turn the log off by setting this value to false.
** $lsrcDebugLog, The name of the file where the log should be written.
** ini_set("log_errors", "1"), Apaches log file (error.log) will get filed with php-errors. Very useful for debugging. Comment this line out (put two forward slashes at the beginning of the line "//") once you have finished setting up and have put your LSRC service into production.
** ini_set("soap.wsdl_cache_enabled", "0"), while testing, caching is not useful. If in productive Mode, turn this on or just comment the line to stick to server defaults.
** (optional) set $lsrcOverSSL to true, if you want SOAP to exchange the messages over SSL resp. https. '''Note:'''Turning this on simply changes the internal addressing to either "https:" or "http:" in order to work over a SSL connection, nothing more.
** set the directories, where the .csv files to import can be found. You will have to export some survey, you want to import and activate with LSRC, first.
** (optional) change $sLsrcSeparator = "your separator"; in lsrc.config.php if you wish to separate tokens for the sInsertToken function with any other separator than default, which is a comma.
** (optional) change $sDatasetSeperator= "your separator"; in lsrc.config.php if you wish to separate Datasets for the sInsertParticipants function with any other separator than default, which are two colons.
** (optional) change $sDatafieldSeperator= "your separator"; in lsrc.config.php if you wish to separate Datafields for the sInsertParticipants function with any other separator than default, which is a semicolon.
* the script needs rights to write files to the folder "admin/remotecontrol/" (lsrc.log, if logging is used and lsrc.wsdl). if(you cannot or don't want to set the directory rights to 777){create those two files(lsrc.log and lsrc.wsdl)in the lsrc dir with the permission to write them(777))
* If you want to save Survey, group or question csv's directly from Limesurvey into the lsrc Folders, you need to set them to 777, too. (Option can be enabled by adding $export4lsrc = true; to Limesurveys config.php)
* You may have to generate a wsdl file if you need a static one. Run lsrc.server.php?wsdl and the script will make a lsrc.wsdl with the correct server url included in the lsrc directory.
* If auto wsdl generation do not work properly (maybe virtual hosts make Problems, please report back, if so or not so, can't test at the moment) You have to set the url of the lsrc.server.php script in the last block of the wsdl

==How to enable OpenSSL / https Support==
* LSRC supports SSL over http resp. https.
* Your Webserver needs to support and enable OpenSSL (See your Webserver Manual)
* '''ATTENTION:''' Just set the Variable $lsrcOverSSL = true; in lsrc.config.php. After that, initialize your client like shown below, a wsdl file with correct URL will be generated automaticly for you:

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

new SoapClient('https://localhost/limesurvey/admin/lsrc.server.php?wsdl',

array('soap_version' => SOAP_1_1,

'trace' => 1));

</syntaxhighlight>
* 'ONLY FOLLOW THIS STEPS IF WSDL GENERATION DOES NOT WORK FOR YOU' <br>There are two locations in the code, where you force the webservice to use https

<nowiki>:</nowiki> 1. On the client side, when you call the SOAP-Server over wsdl. For 'https' do it like that:

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

new SoapClient('https://localhost/limesurvey/admin/remotecontrol/lsrc.wsdl', array('soap_version' => SOAP_1_1,

'trace' => 1));

</syntaxhighlight>

<nowiki>:</nowiki> for 'http' like that:

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

new SoapClient('http://localhost/limesurvey/admin/remotecontrol/lsrc.wsdl', array('soap_version' => SOAP_1_1,

'trace' => 1));

</syntaxhighlight>

<nowiki>:</nowiki> Note that the client will only get the wsdl-definition over https, to get the SOAP Messages over https, set the uri in the wsdl file, like below...

<nowiki>:</nowiki> 2. Here is the most important Step to SSL. At the End of the lsrc.wsdl file, last block, same procedure:

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

<port name='LsrcPort' binding='tns:LsrcBinding'>

<soap:address location='https://localhost/limesurvey/admin/remotecontrol/lsrc.server.php' />

</port>

</syntaxhighlight>

<nowiki>:</nowiki> or for normal http mode:

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

<port name='LsrcPort' binding='tns:LsrcBinding'>

<soap:address location='http://localhost/limesurvey/admin/remotecontrol/lsrc.server.php' />

</port>

</syntaxhighlight>

That's it! all request, response and fault messages will be transported over https...

=How to use LSRC=

==use the client==

'''NOTE on PHP 5.3:''' setting the path2wsdl to http://localhost/limesurvey/admin/remotecontrol/lsrc.server.php?wsdl worked with all prior 5.3 version of PHP. With PHP 5.3 the client will not recognize the wsdl lsrc.server.php?wsdl gives back. You have to call lsrc.server.php?wsdl once to generate the lsrc.wsdl file and then point your client to http://localhost/limesurvey/admin/remotecontrol/lsrc.wsdl instead.

There is a PHPclient (from version 1.86) in the remotecontrol folder. You can use this ClientClass to control Limesurvey from within your PHP Applications with ease.

Take a look at lsrc.testclient-new.php to get an impression of how it can be implemented.

Basically you just have to include the class, prepare the Client and start the function calls.

Example:

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

<?php

/**
* include the client class
*/

include_once("lsrc.client.php");

/**
* initiate the testclient object
*/

$testclient = new lsrcClient();

/**
* prepare the lsrcClient class (initiate the soapClient, set sid if needed)
*/

$testclient->prepare(333);

/**
* set user and password (only needed, when not set in the client class directly)
*/

$testclient->user = 'admin';

$testclient->pass = 'password';

/**
* set the path2wsdl (only needed, when not set in the client class directly)
*/

$testclient->path2wsdl = 'http://localhost/limesurvey/admin/remotecontrol/lsrc.server.php?wsdl';

/**
* call the function to create a survey
*/

$sReturn = $testclient->createSurvey("surveyName" ,

"surveyDescription",

"welcomeText",

"endText",

"surveyAdmins@email.adress",

"Survey Adminsname",

"http://an.end.url",

"Description of End Url",

"template138");

echo $sReturn;

</syntaxhighlight>

This Skript initiates the client. The parameter at prepare, sets the surveyId. In this case it means we are going to create the survey with the Id 333. If you do not give an id, the survey will get a random id.

Next we set the user and password to use. You do not have to do this, as long as the inital values of the client are correct. But you may have to, if you build your app in a way, that different users use the client to create Surveys or edit them.

In the end, the survey is created with the createSurvey Method and the return is echoed.

==using the functions==

You will need a SOAP- or at least RPC-Client to communicate with the LSRC Webservice. How to create such a Client depends on the programming language you use.

The LSRC itself is written in PHP5 using the PHP:SOAP extension with SOAP 1.1.

In PHP you would initiate the Client-object and call a function from the Webservice with code like e.g.:

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

$wsdl="http://localhost/limesurvey/admin/remotecontrol/lsrc.server.php?wsdl";

$client = new SoapClient($wsdl, array('soap_version' => SOAP_1_1,

'trace' => 1));

try

{

$sReturn = $client->sInsertToken($user, $pass, $iVid, $sToken);

}

catch (SoapFault $fault)

{

$sOutput .= " <br/><br/>SOAP Error: ".$fault->faultcode." : ".$fault->faultstring;

}

</syntaxhighlight>

The LSRC offers some functions:

(<span style='color:#FF0000'>m</span>) means: Mandatory Parameter

==sCreateSurvey==

<span style='color:#FF0000'>Parameters changed after 1.81+! (sVend added)</span>
* String sCreateSurvey($sUser, $sPass, $iVid, $sVtit , $sVbes, $sVwel, $sVend, $sMail, $sName, $sUrl, $sUbes, $sVtyp )
** '''Purpose''': Creates a new survey. It imports an exported survey from any LS v1.xx. and changes some fields (in the current Version it changes SurveyTitle, SurveyDescription and SurveyWelcomeText, adminemail, adminname, url and url_description to the string which was given by the client.)
** '''Parameters''':
*** (<span style='color:#FF0000'>m</span>) string USER, this have to be an existing Useraccount with appropriate rights
*** (<span style='color:#FF0000'>m</span>) string PASSWORD, this has to match the password for the account.
*** (<span style='color:#FF0000'>m</span>) int $iVid, SurveyID desired ID for the Survey, make sure it doesn't already exist in LimeSurvey
*** (<span style='color:#FF0000'>m</span>) string $sVtit, SurveyTitle, should be the (Nr +)Name of the Event to be evaluated
*** (<span style='color:#FF0000'>m</span>) string $sVbes, Survey Description, This should be String put together with veransttyp + doztitle + dozname
*** string $sVwel, Survey Welcometext, A text shown before the survey starts. If not given it says: "Herzlich Willkommen zur Evaluation von "$sVtit"
*** string $sVend, Survey Endtext, Text shown at the endpage.
*** string $sMail, Admin Email, Email Adress of the responsible person for this survey
*** string $sName, Name of the responsible person for this survey
*** string $sUrl, Url of the Link, shown on the last page of survey.
*** string $sUbes, Description String of the URL above. ( <a href='$sUrl'>$sUbes</a> )
*** string $sVtyp, The type of Event that should be evaluated. Use in combination with sAvailableModules with $mode='core' to get all available "types"
** '''Returns''':
*** if everything went fine, it returns the SurveyID from the created survey
** '''Possible Faults''':
*** throw new SoapFault("Authentication: ", "User or password wrong");
*** throw new SoapFault("Database: ", "SurveyID already exists");
*** throw new SoapFault("Server: ", "Mandatory Parameters missing");
*** throw new SoapFault("Server: ", "Import went wrong somehow");
** '''Note''':
*** Goto line 714 in lsrc.helper.php to see what can be done and customized while importing.
*** If you want Limesurvey to give your Survey a random Number if the given ID exist (because you do not need a specific identification for your surveys), just go into the function sCreateSurvey in lsrc.server.php and delete or comment out the if($lsrcHelper->surveyExists($iVid)) clause. In Result, Limesurvey will give your survey a random ID when the given ID exists.

==sActivateSurvey==
* String '''sActivateSurvey'''(string USER, string PASSWORD, int SurveyID, date start, date end)
** '''Purpose''': Activates an existing survey and set start and enddate optional
** '''Parameters''':
*** (<span style='color:#FF0000'>m</span>) string USER, this have to be an existing Useraccount with appropriate rights
*** (<span style='color:#FF0000'>m</span>) string PASSWORD, this has to match the password for the account.
*** (<span style='color:#FF0000'>m</span>) int SurveyID, the SurveyID for the Survey to activate.
*** date start, date for the Survey to start. 2008-10-22 means it starts exactly at 2008-10-22 00:00:00 Servertime
*** date end, date for the Survey to end. 2008-10-22 means it ends exactly at 2008-10-22 23:59:59 Servertime. Nobody can access nor complete the Survey only a second later.
** '''Returns''':
*** if everything went fine, it returns the SurveyID from the activated survey
** '''Possible Faults''':
*** throw new SoapFault("Authentication: ", "User or password wrong");
*** throw new SoapFault("Database: ", "Survey you want to activate does not exists");
*** throw new SoapFault("Server: ", "Mandatory Parameters missing");
*** throw new SoapFault("Server: ", "Activation went wrong somehow");
** '''Note''':
*** You can set startDate and/or endDate after activation if needed. Just run the function again with desired parameters.

==sImportGroup==
* String '''sImportGroup'''(string USER, string PASSWORD, int SurveyID, String Module, String groupName, String groupDescription)
** '''Purpose''': Imports an exported group file (.csv) to the Survey given by SurveyID
** '''Parameters''':
*** (<span style='color:#FF0000'>m</span>) string USER, this have to be an existing Useraccount with appropriate rights
*** (<span style='color:#FF0000'>m</span>) string PASSWORD, this has to match the password for the account.
*** (<span style='color:#FF0000'>m</span>) int SurveyID, the SurveyID
*** (<span style='color:#FF0000'>m</span>) string Module, the filename of the Group you want to add to the Survey. Use sAvailableModules to get the available groups.
*** string groupName, the Title the Group gets. If not set, it will use the title given in the .csv.
*** string groupDescription, Description of the group. If not set, it will use the description given in the .csv.
** '''Returns''':
*** if everything went fine, it returns the String "Import OK"
** '''Possible Faults''':
*** throw new SoapFault("Authentication: ", "User or password wrong");
*** throw new SoapFault("Authentication: ", "You have no right to change Surveys from other people");
*** throw new SoapFault("Server: ", "Survey Module $sMod does not exist");
*** throw new SoapFault("Server: ", "Group does not support Surveys Baselanguage ($langcode)");
** '''Note''':
*** It imports only exported groups as .csv which lay under \groups or any other dir given in lsrc.config.php
*** <strike>It imports only the files beginning with "mod_" ending with ".csv"</strike>
*** The Param Module must only contain the "name of the Module": Only the String before ".csv"
*** The baselanguage of the group to import, have to match the baselanguage of the coresurvey.

==sImportQuestion==
* String '''sImportQuestion'''(string USER, string PASSWORD, int SurveyID, String Module, String mandatory)
** '''Purpose''': Imports an exported question file (.csv) to the last group of the Survey given by SurveyID. This is meant for predefined questions stored in the /question directory
** '''Parameters''':
*** (<span style='color:#FF0000'>m</span>) string USER, this have to be an existing Useraccount with appropriate rights
*** (<span style='color:#FF0000'>m</span>) string PASSWORD, this has to match the password for the account.
*** (<span style='color:#FF0000'>m</span>) int SurveyID, the SurveyID
*** (<span style='color:#FF0000'>m</span>) String Module, the name of the csv file you want to add to the Survey, without extension(.csv).
*** String mandatory, default='N' set to 'Y' if you want that question mandatory
** '''Returns''':
*** if everything went fine, it returns the String "OK"
** '''Possible Faults''':
*** throw new SoapFault("Authentication: ", "User or password wrong");
*** throw new SoapFault("Authentication: ", "You have no right to change Surveys from other people");
*** throw new SoapFault("Server: ", "Group does not support Surveys Baselanguage ($langcode)");
** '''Note''':
*** It imports only exported questions as .csv which lay under \questions or any dir given in lsrc.config.php
*** The baselanguage of the question to import, have to match the baselanguage of the core survey.

==sImportFreetext==
* String '''sImportFreetext'''(string USER, string PASSWORD, int SurveyID, String questionTitle, String questionText, String questionhelp, String module='freitext', string mandatory)
** '''Purpose''': Imports an exported question file (.csv) to the last Group of the survey given by SurveyID and changes the Title, question and helptext. This is meant for importing empty question.csv's (Text Questions)
** '''Parameters''':
*** (<span style='color:#FF0000'>m</span>) string USER, this have to be an existing Useraccount with appropriate rights
*** (<span style='color:#FF0000'>m</span>) string PASSWORD, this has to match the password for the account.
*** (<span style='color:#FF0000'>m</span>) int SurveyID, the SurveyID
*** String questionTitle, Name or Categorie of the Question
*** String questionText, The Question itself
*** String questionhelp, A little Help text for better understanding of the Question
*** String module, the name of the Module you want to add to the Survey. It should be "Freitext" by default.
*** String mandatory, make the question mandatory by giving 'Y' as this param.
** '''Returns''':
*** if everything went fine, it returns the String "OK"
** '''Possible Faults''':
*** throw new SoapFault("Authentication: ", "User or password wrong");
*** throw new SoapFault("Authentication: ", "You have no right to change Surveys from other people");
*** throw new SoapFault("Server: ", "Group does not support Surveys Baselanguage ($langcode)");
** '''Note''':
*** It imports only exported questions as .csv which lay under \questions or any dir given in lsrc.config.php
*** It is meant for importing one shortext, Longtext or Hugetext Question and changing the Question and Helptext.
*** The baselanguage of the question to import, have to match the baselanguage of the core survey.
*** Be sure to have at least one proper .csv (Freitext.csv) in the proper directory (questions), to use this function.
*** Use sAvailableModules with mode='que' to get all question .csv's available.

==sImportMatrix==
* String '''sImportMatrix'''(string USER, string PASSWORD, int SurveyID, String Module, String questionText, String questionhelp, String questionItems)
** '''Purpose''': Imports an exported question file (Matrix5.csv) to the Survey given by SurveyID and changes the question, helptext and gives Items to the 5 Scale Matrix. This is meant for importing one 5 Scale Matrix Question.
** '''Parameters''':
*** (<span style='color:#FF0000'>m</span>) string USER, this have to be an existing Useraccount with appropriate rights
*** (<span style='color:#FF0000'>m</span>) string PASSWORD, this has to match the password for the account.
*** (<span style='color:#FF0000'>m</span>) int SurveyID, the SurveyID
*** string Module, the name of the Module you want to add to the Survey. It should be "Matrix" by default.
*** String questionText, the question or text to the Matrix
*** String questionhelp, the help text
*** String questionItems, the Items that should be rated, separated by commas
** '''Returns''':
*** if everything went fine, it returns the String "OK"
** '''Possible Faults''':
*** throw new SoapFault("Authentication: ", "User or password wrong");
*** throw new SoapFault("Server: ", "Group does not support Surveys Baselanguage ($langcode)");
** '''Note''':
*** It imports only exported groups as .csv which lay under docs\demosurveys\studiply_mod
*** It is meant for importing a group with only one 5 Scale Matrix Question and changing the Question and Helptext and add Items.
*** Be sure to use an user with the surveys baselanguage as default, because this language is used to fill the language fields for answers and questions while importing.

==sAvailableModules==
* String '''sAvailableModules'''(string USER, string PASSWORD, string mode)
** '''Purpose''': Returning all the csv Names of the csv's in the Directorys configured in lsrc.config.php
** '''Parameters''':
*** (<span style='color:#FF0000'>m</span>) string USER, this have to be an existing Useraccount with appropriate rights
*** (<span style='color:#FF0000'>m</span>) string PASSWORD, this has to match the password for the account.
*** String mode, (optional) "mod" for the available groups, "core" for the coreSurveys, "que" for addable questions. Default, when not given is "mod".
** '''Returns''':
*** if everything went fine, it returns a String with all surveys, groups or questions (depends on mode) in the Dir given in lsrc.config.php, separated by comma.
** '''Possible Faults''':
*** throw new SoapFault("Authentication: ", "User or password wrong");
** '''Note''':

==sSendEmail==
* String sSendEmail($sUser, $sPass, $surveyID, $type, $maxLsrcEmails='', $subject='', $emailText='')
** '''Purpose''': sends Emails to Participants of a particular survey
** '''Parameters''':
*** (<span style='color:#FF0000'>m</span>) string USER, this have to be an existing Useraccount with appropriate rights
*** (<span style='color:#FF0000'>m</span>) string PASSWORD, this has to match the password for the account.
*** (<span style='color:#FF0000'>m</span>) int surveyID, Id of the survey from which participants will be mailed
*** (<span style='color:#FF0000'>m</span>) string type, the kind of email you like to send (invite, remind or custom)
*** int $maxLsrcEmails, if you want to override $maxemails setting in config.php for sending mails with lsrc: here you go.
*** string subject, only needed if type==custom, the subject for the mail to be send.
*** string emailText, only needed if type==custom, the text for the mail to be send.
** '''Returns''':
*** "X Mails send" or "No Mails to send" in custom mode.
*** "X Mails send. X Mails left to send" or "No Mails to send" in invite mode.
*** "X Reminders send. X Reminders left to send" or "No Reminders to send" in remind mode.
** '''Possible Faults''':
*** throw new SoapFault("Authentication: ", "User or password wrong");
*** throw new SoapFault("Server: ", "Mandatory Parameters missing");
*** throw new SoapFault("Type: ", "Wrong send Type given. Possible types are: custom, invite or remind");
** '''Note''':
*** invite: When $maxemails is set the function sends only $maxemails in one go. If you call it again, it will go on to send the invitations, until everyone is invited.
*** remind: When $maxemails is set, it will only send $maxemails in one go. It checks if reminders have been send to other participants and if there are participants who received less reminders than others, the script will first send reminders to those who have not been reminded so often, until the remindercount is equal.
*** custom: $maxemails have no effect in custom mode. I have no solution for counting those who have been mailed before.

==sInsertToken==
* String '''sInsertToken'''(string USER, string PASSWORD, int SurveyID, string Token)
** '''Purpose''': Creates and populates a table {dbprefix}token_{SurveyID} and thus "closes" the survey. It is possible to add tokens to the existing table.
** '''Parameters''':
*** (<span style='color:#FF0000'>m</span>) int SurveyID, ID of the survey to close with a token table
*** string Token, a string with comma separated tokens. There is a possibility to set any other separator in config.php. Max. tested length of a string was 500,000 tokens, that makes a String of 5,500,000 Chars, this is just the limit of the apache webserver on my notebook (CoreDuo 1,6MHz, 1GB Ram) with default Resource Limits (60,60,16). I recommend to send max. 100,000 tokens over the webservice. Repeat for more tokens.
*** (<span style='color:#FF0000'>m</span>) string USER, this have to be an existing Admin-, Superadmin- or Useraccount with the rights to create and activate Surveys
*** (<span style='color:#FF0000'>m</span>) string PASSWORD, this has to match the password for the account.
** '''Returns''':
*** if everything went ok, it returns the String: "[X] Token given, [X] Token inserted"
** '''Possible Faults''':
*** throw new SoapFault("Authentication: ", "User or password wrong");
*** throw new SoapFault("Database: ", "Survey does not exists");
*** throw new SoapFault("Server: ", "Token could not be inserted");
** '''Note''':
*** Make sure on the client side that no token appears twice in the table. There is no check on this and won't be in the future. What happens if there are two same tokens? 2 participants will get the same token, one will fill out the form for both, and the other will get a message: "your token have already participated"
*** If there is no token table, it will create one and add the tokens.
*** If the Tokentable already exists, it just adds the given tokens to the existing table.

==sInsertParticipants==
* String '''sInsertParticipants'''(string USER, string PASSWORD, int SurveyID, string ParticipantData)
** '''Purpose''': Creates and populates a table {dbprefix}token_{SurveyID} and thus "closes" the survey. You can deliver some data to the token table. If you do not support a token, or an empty String as token, a unique token will be generated for the participant.
** '''Parameters''':
*** (<span style='color:#FF0000'>m</span>) int SurveyID, ID of the survey to close with a token table
*** string ParticipantData, The Data have to be in the right Syntax, it's like this:

<pre>

FIRSTNAME;LASTNAME;EMAIL;ATTRIB1;ATTRIB2;TOKEN::FIRSTNAME;LASTNAME;EMAIL;ATTRIB1;ATTRIB2;TOKEN

</pre>

'''NOTE: The Data Syntax change with 1.86'''. in order to take language, validfrom, validuntil and a variable count of attributes.

With 1.86 and later versions, it will have to be like this:

<pre>

FIRSTNAME;LASTNAME;EMAIL;LANGUAGE;TOKEN;VALIDFROM;VALIDUNTIL;attribute1,attribute2,attribute3::FIRSTNAME ... etc.

</pre>

note that the 8th field is the attributes field. There is no 9th field. You can seperate many attributes with a colon (,). The lsrc will create the needed fields in the db if they are not present. All Fields after LANGUAGE are optional and do not have to be send.

seperate the Datasets with double colons (::) and the fields with semicolon (;). The '''attrib1, attrib2 and token fields are optional''', you can just leave them out if not used. Note that the attrib field will get empty and not NULL, by now there where no complications, inform us, if you see some difficulties in not setting them NULL. Max. successfully tested length of a string was 3,000,000 Chars, this is just the limit of the apache webserver on my notebook (CoreDuo 1,6MHz, 1GB Ram) with default Resource Limits (60,60,16). I recommend to send max. 10,000 Datasets over the webservice at once(~1,000,000 chars). Repeat for more Datasets.
*** (<span style='color:#FF0000'>m</span>) string USER, this have to be an existing Admin-, Superadmin- or Useraccount with the rights to create and activate Surveys
*** (<span style='color:#FF0000'>m</span>) string PASSWORD, this has to match the password for the account.
** '''Returns''':
*** if everything went ok, it returns the String: "[X] Datasets given, [X] rows inserted. ";
** '''Possible Faults''':
*** throw new SoapFault("Authentication: ", "User or password wrong");
*** throw new SoapFault("Server: ", "No SurveyId given");
*** throw new SoapFault("Database: ", "Survey does not exists");
** '''Note''':
*** default tokenlength is 5 chars, if you want to change the length, goto lsrc.server.php, line 441
*** If the token table does not exists, it will be created, and if it does, the data will be added.

==sTokenReturn==
* string return '''sTokenReturn'''(string USER, string PASSWORD, int SurveyID)
** '''Purpose''': Gives back all Tokens, which did not complete the Survey, in a String seperated by commas.
** '''Parameters''':
*** (<span style='color:#FF0000'>m</span>) int SurveyID, the ID for the Survey from which you want get the unused tokens
*** (<span style='color:#FF0000'>m</span>) string USER, this have to be an existing Admin-, Superadmin- or Useraccount with the rights to create and activate Surveys
*** (<span style='color:#FF0000'>m</span>) string PASSWORD, this has to match the password for the account.
** '''Returns''':
*** Returns a String, a string of all unused tokens seperated by comma.
** '''Possible Faults''':
*** throw new SoapFault("Authentication: ", "User or password wrong");
*** throw new SoapFault("Database: ", "Survey does not exists");
*** throw new SoapFault("Server: ", "No SurveyId given");
*** throw new SoapFault("Database: ", "Token table for this Survey does not exists");
*** throw new SoapFault("Database: ", "No unused Tokens found");

==sGetFieldmap==
* string return '''sGetFieldmap'''(string USER, string PASSWORD, int SurveyID)
** '''Purpose''': Gives back the fieldmap for the survey

for example:

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

"fieldname","type","sid","gid","qid","aid","title","question","group_name","lid","lid1"

"111X779X39801","F","111","779","3980","1","1","How do you feel?","Paticipant feelings","",""

"111X779X39802","M","111","779","3980","2","1a","Why do you feel like this?","Paticipant feelings","",""

[...]

</syntaxhighlight>
** '''Parameters''':
*** (<span style='color:#FF0000'>m</span>) int SurveyID, the ID for the Survey from which you want to get the Fieldmap.
*** (<span style='color:#FF0000'>m</span>) string USER, this have to be an existing Admin-, Superadmin- or Useraccount with the rights to create and activate Surveys
*** (<span style='color:#FF0000'>m</span>) string PASSWORD, this has to match the password for the account.
** '''Returns''':
*** Returns a String, a string of the fieldmap, seperated by comma and blanks
** '''Possible Faults''':
*** throw new SoapFault("Authentication: ", "User or password wrong");
*** throw new SoapFault("Authentication: ", "You have no right to get fieldmaps from other peoples Surveys");
*** throw new SoapFault("Database: ", "Survey does not exists");
*** throw new SoapFault("Server: ", "No SurveyId given");

==fSendStatistic==

<span style='color:#FF0000'>''(since 1.86)''</span>
* '''fSendStatistic'''(string USER, string PASSWORD, int SurveyID, string Email, string doctype, string graph)
** '''Purpose''': sends an Statistic File as Attachment
** '''Parameters'''
*** user: Limesurvey user
*** password: Limesurvey Password
*** surveyId: ID of the survey from which statistics should be generated
*** email: the adress to which the statistic file is send
*** doctype: pdf, xls or html. With pdf or xls, the recipient gets an attached file with a short notice. With html, he gets an html e-mail without attachments
*** graph: turn graph generation on or off. Works only with pdf generation. Use '1' as a string if you want to enable it
** '''returns'''
*** string: 'XLS send'
*** string: 'PDF send'
*** string: 'HTML send'
** '''possible Faults'''
*** throw new SoapFault("Server: ", "Mandatory Parameters missing");
*** throw new SoapFault("Authentication: ", "User or password wrong");
*** throw new SoapFault("Authentication: ", "You have no right to send statistics from other peoples Surveys");
*** throw new SoapFault("Database: ", "Survey does not exists");
*** throw new SoapFault("Mail System", "Mail could not be send! Check your E-Mail Settings.");

=Testing=

For testing purposes, we made a testclient in php. Therefore you need a webserver to run it. If you test on one machine you need nothing to do, you can go to http://localhost/limesurvey/admin/lsrc/lsrc.testclient.php in your browser to test the webservices functionality.

Of Course this is very boring, because the apache talks with himself (and thats not the primary matter of a webservice).

The Testclient have two purposes:

1. It checks the Server(the one the testclient is running on!) for the PHP:SOAP Extension and installed libXML version and gives feedback if the enviroment does support SOAP via PHP:SOAP. This is very useful to check your Server and your Client towards PHP:SOAP compatibility. In addition to this, it will check if the wsdl file you want to connect to exists, it does not validate the wsdl file.

2. You can test the functions of the webservice.

If you test the webservice in realistic enviroment (two machines) you have to customize three things
* the lsrc.testclient.php needs to be on the machine where the webservice is NOT running, but it needs a webserver... download xampp from apachefriends if you dont have one <strike>(caution for Linux Users: you have to compile PHP5 with SOAP and enable the extension, futhermore you have to install libXML2. Last thing can by done very easy via Synaptics or apt-get)</strike> xampp for Linux works well with SOAP and libXML from version 1.7.
* this Line:

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

$limeUrl='https://localhost/limesource/limesurvey';

</syntaxhighlight>

At the beginning of lsrc.client.php (used by lsrc.testclient.php) set the target Limesurvey Installation Dir. localhost for servername is always wrong in this testcase, 127.0.0.1, too.

'''NOTES''':
* The Testclient is configured to use "admin" "password" as authentication. If you want to test with another user or password you have to set this vars in lsrc.testclient.php ( lines 40 and 41)
* If you just get a blank page on the testclient, make sure the path to the wsdl is correct, and the var $enableLsrc is set to true in config.php or lsrc.config.php

=Notes=
* Security is enhanced: no action without permission (as good as Limesurveys Security itself --> very good)
* No headers or "Quick and Dirtys" anymore, no Scripts, just functions and a class.
* All configuration Variables are stored in lsrc.config.php by now
* There is a debug functionality, showing where the script runs through the code in an own log file. Use Apaches error.log in addition to find errors if you got any.
* LSRC is part of LimeSurvey, therefore it stands under GNU/GPL License v2 or later.
* SOAP Services and therefore LSRC only support UTF-8 charsets.
* LSRC works with AdoDB (MySql,Postgresql, MSSQL) .
* LSRC is tested, but under steady development, use on your own risk, test the functions before using them productively!

=Changes=

1.86
* new function fSendStatistics: to send statistics as attachment to an e-mail-address
* Datasyntax for sInsertParticipants changed in order to take validfrom, validuntil, language and a variable Set of attributes.

1.85
* Several improvements to stability.

1.82
* Added sVend Parameter to sCreateSurvey, to set the endtext
* sInsertParticipants takes a token in the dataset, however, if non is supported, it will be generated.
* a new variable $enableLsrc is introduced to enable the Lsrc only when it is used.
* a serious exploit has been fixed.

1.81
* Added sGetFieldmap function.
* The template.csv's changed.
* exported csv's prior 1.81 will not import over lsrc anymore. Import them via Browser and export them back to lsrc.

1.80 => 1.81
* Changed sImportGroup: imports '''all''' groups under $modDir, adds them to the survey. Not only the ones with mod_ as prefix. In addition, you can give Name and Description of the Group.
* New sImportQuestion: imports questions in $queDir and adds them to the last group
* New sImportFreetext: imports a Freetext question and changes the title and question to the Strings given. Previously, this function was called sImportQuestion.
* Changed sAvailableModules: type can be core, mod or que. "que" is new and gives back the names of all the questions available.
* New sSendEmail: send invitations, reminders and custom mails to participants of a survey over Limesurvey.

=ToDo / ToCome=
* <strike>sInsertParticipants should take a lang attribute for each participant</strike>

please add your feature requests to the [http://bugs.limesurvey.org bugtracker] if it is not listed here...

=Security=

There have been a security hole in the versions prior 1.82 (1.80RC2 to 1.81+). This leak could be used to compromise your webspace if it is weakly configured.

To minimise the risk of a security leak endanger your system, we disabled the lsrc by default with version 1.82 and you have to enable it explicity in your config.php.

Some things you can do to improve your security when using the lsrc:
* instead of setting the remotecontrol folder to 777, just create an empty file lsrc.wsdl with the rights 777
* disable the lsrc.log in lsrc.config.php
* Do not set the survey, groups, questions folders to 777 for saving lsrc templates directly within Limesurvey, instead, save the .csv on your local PC and upload them via ftp to the folders.
* delete lsrc.testclient.php, when in productive use. Lsrc.testclient.php could be used from unauthorized people to perform portscanning on other machines. The attacked webserver would be seeing your webserver as attacker, altough you did not perform any attack by yourself. This is not so serious, as this bahaviour of the testclient is not much valuable for any serious hacker.

Project ideas for GSOC 2010

2010-04-01T13:06:27Z

Rakete:

__TOC__

=Welcome=

Welcome Google Summer of Code Student aspirants (:razz:)!! Please check if you are an [http://socghop.appspot.com/document/show/gsoc_program/google/gsoc2010/faqs#student_eligibility eligible candidate] for the GSoC program.

This page lists project ideas developed by the LimeSurvey Community. These tend to be areas that will get the most support as projects since they have been developed by people who know the project and what it needs the most. '''However''', if you have your own idea for a project discuss your awesome idea with us in our [http://www.limesurvey.org/component/option,com_fireboard/Itemid,105/func,view/catid,11/id,24710/lang,en/ forums], [https://lists.sourceforge.net/lists/listinfo/limesurvey-developers mailing list] or at #limesurvey on irc.freenode.net. Then submit '''your''' proposal. Good Luck (:biggrin:)

=Project ideas=

==Example Format...==

Describe the idea here in general terms

'''Skills'''

Explain what sort of coding skills would be needed for a student to implement this project

'''Difficulty'''

Explain the level of difficulty involved

'''Probable Mentors'''

Put your name (and tag) here if you are willing to mentor a student for this idea

==Limesurvey I: Modularisation of basic functions, that are needed by LSRC==

Currently the LSRC is suffering from a lack of experience back in the days I began to implement its features. Unfortunaly some functions tend to become buggy when limesurvey-development takes steps forwards, because the LSRC functions are mostly an adapted copy of code from limesurveys original scripts.

The main Idea is to realize the vital functions (at least: importSurvey and activateSurvey) in a way, that Limesurvey and the LSRC can use it together and the code have to be maintained only once.

Primary Goals:

- analyse the current differences between lsrc.helper functions and the original Limesurvey scripts. Especially for activateSurvey and importSurvey

- make a concept on how to realize a modular function from the original script, which can be called from limesurvey and the lsrc (see statistics.php and statistics_function.php in comparison as example)

- modularize the script to a function and build it in.

Secondary Goals:

- modularize insertParticipant or implement new functions, which can be used by limesurvey and LSRC in the same manner.

'''Skills'''

PHP, AdoDb/sql, PHP:SOAP

'''Difficulty'''

intermediate

'''Probable Mentors'''

Tim Wahrendorff (rakete)

==LimeSurvey 1: Email bounce tracking & handling of international email addresses==

Currently there is no way to process email bounces of invitation or reminders in an automated way. If a bounce is received the administrator has to manually process every bounce - either by finding out a correct email address or removing the participant completely. Additionally it would be great if LimeSurvey could handle International email addressing - although the RFC for this kind of features are still experimental it would be great if we can be ahead of time. Primary goals of this task:

- Create a facility to handle email bounces using various methods. Easier to install methods which run without CRON jobs and with a single email account - more advanced and safer methods which require certain email server setups. Make it quick and easy to configure and handle. Create followup actions in case an email is bounced. Differentiate between bounces and other 'away-messages'.

- Extend the PHPmailer library and LimeSurvey so it can handle international email addressing (including configuration)

Skills

PHP, knowledge of email handling and RFCs, some HTML & JS

Difficulty

Medium

Probable Mentors

Carsten Schmitz (c_schmitz)

Thibault LeMeur (lemeur)

==LimeSurvey 1: File Upload question type==

The idea is to have a question type in LimeSurvey1 where survey participants can upload one (or more) files. Often in surveys the participant is asked to create some content (pictures, movies, documents, etc.) to upload as an answer to a question. The following goals are primary in this task:
*Easy handling for the participant (uploading one or more files should be a piece of cake - also removing files if accidentally the wrong file was uploaded)
*Extensive configuration options for the question type like
**How many files are required, minimum and maxim number of files,
**maximum/minimum upload size,
**Allowed file types
*Safe!! storage in the file system, checks for file contents
*Implementation in statistics / data entry / printable survey / response browsing / response editing & RemoteControl
*Administrator can download one or more files (zip-packaging files for download) from one response and across responses
*Provide possible hooks for third party processing tools

'''Skills'''

PHP, jQuery, AJAX - existing knowledge on the general idea and related security would be of big advantage

'''Difficulty'''

Medium

'''Probable Mentors'''

c_schmitz (Carsten Schmitz)

==LimeSurvey 1: Authentication framework==

The idea is to design and implement a generic authentication framework for LimeSurvey 1 as well as some authentication modules. The Authentication framework will make it possible to implement any kind of authentication backend apart from the already existing internal-DB and Web server delegation schemes. Currently authentication is only used for the survey-administration GUI and not the participants interface (tokens are used for this). With the new authentication framework it will be possible to define several authentication backends and use some of them for participants-authentication.

The generic authentication framework must define the following services:
* User authentication: this interface must return the identity of the authenticated user if authentication is successful.
** Authentication may not always be based on a simple user/password form, so the proposed framework must be generic enough to enable authentication based on other schemes (using any numbers or GET/POST parameters or any other contextual parameter such as Referrer, session variable...
* User provisionning:
** when activated on the survey administration interface, an authentication module might be able to create a newly authenticated user into the LimeSurvey internal DB (which is required for setting the user rights on the platform). The newly created user can be assigned a default profile or a per-user profile (queried from an external database).
** when activated on the participants interface, the authentication module will provision the token table of the correspoding survey (only if the token for this user has not been already added).

The already existing authentication schemes will be ported to the new framework (internal-DB and Web server authentication delegation) and at least a new one will be implemented (openID, CAS, Shibboleth).

'''Skills'''

PHP, SQL, Authentication protocols (openID, CAS, LDAP-bind, ...)

'''Difficulty'''

Medium

'''Probable Mentors'''

lemeur (Thibault Le Meur)

'''Want to know more'''

Please read the [http://docs.limesurvey.org/tiki-index.php?page=GSOC+2010++Authentication+framework#FAQ FAQ about this project]

==LimeSurvey 2: Db Storage Engine==

Develop an extensible plugin survey storage engine for LimeSurvey 2.

<u>Description</u>

Other than survey design, everything that happens in LimeSurvey centres around the ability to save responses to questions to a database, and retrieve the responses again when required. Historically these functions have been incorporated within the various functions of LimeSurvey and this has locked LimeSurvey to a single methodology for data storage and retrieval and made future modifications and improvements difficult if not possible.

For this project we are looking for students to write a 'middleware' that exposes abstract high-level functions to LimeSurvey 2 (e.g.: storing these answers related to this question, running statistical analysis etc.) but is built in top of Cake's 'low-level' operations (such as find, save etc). The aim is to abstract away from a specific DB implementation and provide an intuitive and rich API for LS2.

<u>Rationale</u>

Because the interface with the data storage system is so critical to practically every other function in LimeSurvey we want to develop a stand-alone module that is transportable and extensible for the future. And by keeping the logic of data and survey storage separate from the rest of LimeSurvey’s functions we will the ease with which LimeSurvey can be developed in the long term.

<u>Implementation</u>

This is such an important project that we would consider multiple students undertaking the task. In conjunction with a strong understanding of data structures, php coding and api principles the students would also have to display a capacity to work in a team and with the broader community.

The implementation would focus on becoming a plugin/addon module under CakePHP which uses the default CakePHP database systems to the absolute minimum. In a well implemented version of this proposal only simple SQL inserts, queries and updates would be required. All other logic would be managed by the engine.

<u>Requirements & Considerations</u>

The DB Engine must be able to do the following
* ease development of additional '''question types, which will be developed as plugins'''
* '''efficient data retrieval''', especially summaries (e.g. display 100 last responses)
* support '''generic''' data storage and retrieval - aside surveys, imagine running online admission tests, polls, sign-up forms, volunteer campaign etc. etc.
* easily support conditions, looped question, or generally, '''non-linear data'''. Think of a survey that asks how many children you have and then asks information about each of them.
* support questions that have multiple '''answers and multiple types of answers'''. Think of a question asking "What is your favourite ice cream?", offering 3 fixed options and last one allowing user to enter a custom answer.
* support survey resuming (where applicable)

<u> Use Cases </u>

Think of these when writing your proposal
# Questionnaire which has a special section displayed only if a user answers a chosen question in a specific way (i.e. branching)
# Question on your favourite ice-cream, with an option "Other", upon which the user will be asked to enter his own choice (i.e. multi-datatype question types)
# Questionnaire, which asks how many children you have and then loops a set of predefined questions that many times. (i.e. looping)

<u> Your proposal </u>

Your proposal needs to be fairly detailed and must dig deep down to the implementation level, with good analysis of the performance. "Read the data from the user and store it in the database" is no good! How are you going to store it? What is the schema going to be? Does it satisfy the requirements, for branching, conditions, pluggable question types? Does it scale well? Is it efficient - what is the time complexity? Can I get summaries out of it in a reasonable time? All this needs to be addressed. Early submissions are accepted by both mentors and suggestions and comments will be given (:wink:).

<u>Field Naming and Database Extensibility Methodologies</u>

An ongoing debate in the LimeSurvey community has been the method in which the database stores survey results. In LimeSurvey 1 a flat database schema was used whereby once the survey designer had finished setting up the survey a database table was created with a field for every individual question/answer combination. The advantages of this database schema were speed of retrieval for reporting and exporting and searching. The disadvantages were that the survey system had to ‘freeze’ the structure in place once the table was created (therefore the activate/de-activate rules in LimeSurvey 1). The single table method doesn’t allow easy storage of metadata for individual question/answer combinations (such as timestamps). Nor does it lend itself to surveys with enormous quantities of question/answer combinations – sometimes running up against database limitations regarding the number of fields per table.

An alternative is a ‘normalised’ database topology where a single table is created to store all survey responses – one database row per question/answer combination. A related table would store metadata that is directly related to the survey sitting/session rather than the answer (e.g.: username, ip address, geographical location, user demographic). The advantage to this methodology is the increased flexibility (extensible) which would allow modification of surveys at any stage even after data has been collected (see requirements). The disadvantages are that searching and compilation of data is complicated and resource intensive.

In a perfect world LimeSurvey would allow users to choose either methodology – either at an installation level or even on a per-survey level.

Having a database storage engine effectively acting as an API would allow this functionality to be built, but the choice of database topology would be invisible to the related LimeSurvey functions that require data.

'''Skills'''

PHP, CakePHP, Database Schema Design, Sound knowledge of Algorithms and Data Structures

'''Difficulty'''

High

'''Probable Mentors'''

jasebo (Jason Cleeland)

macduy (Mac Duy Hai)

==LimeSurvey 2: Template Editor==

Limesurvey 2 needs a nice and powerful template editor so everyone can create a template which matches their requirements.

'''Skills'''

One needs to know about the details of the [http://dwoo.org/ dwoo template engine] which is used at LS2. There is some cakePHP coding needed to create an interface and write changes to the template files as well as some HTML/CSS to create a nice interface.

'''Difficulty'''

You don't have to create difficult algorithms for this task. It's useful if you have worked with templates for another web-application or take a detailled look at [http://docs.limesurvey.org/tiki-index.php?page=Themes%3A+Templates+and+Styles&structure;=English+Instructions+for+LimeSurvey how templates work in Limesurvey]. Some design/usability background would be nice but is not a must.

'''Probable Mentors'''

Mazi

==LimeSurvey 2: Mini-projects==

Mini-projects is a collection of small-to-medium sized projects, which you mix-and-match according to your tastes. Heck, you can even roll your own idea and once reviewed and approved, you can code away. Some recommended/important mini-projects and their brief descriptions:
*'''Smarter installer:''' LS2.0 comes with its own installer, though it may not be the friendliest to use. Your task is to make it juicier to use:
** Resume installation - if the user aborts the installation mid-way, make it easy for him to resume it. It should be able to clean up databases, revert files and basically be prepared for any eventuality.
** Better error handling - meaningful error reports, suggestions how to fix them: e.g. "Database does not exist" is better than "Database error" (and excellent opportunity for a "Would you like to create it?" button)
** Customization - invite the user to customize his installation of LimeSurvey - from security settings such as salt, to interface such as the header title.
*'''User management:''' When the number of users grow, it becomes increasingly harder to manage them. Implement functionality and provide interface for features that would make this task easier. Inspire yourself by the big players, such as the infamous you-know-which-one social website.
**'''Groups within groups:''' LS2 users can belong to a group, but groups cannot belong to other groups.
**'''Contact lists:''' There is already something called AssignmentGroups. Study this concept carefully and generalize to a Contact List
**'''GUI:''' Design a GUI which allows you easily manage users, groups and contact lists.
**'''Searching:''' Provide an efficient but simple-to-use search interface and functionality
**'''Batch import:''' import users through CSV, XML, etc...
**'''Batch processing:''' Add an interface to manipulate (add & modify) several users at once
*'''Announcements:''' Make it easy to send customizable announcements to desired audience. Obviously, you don't want to send reminder e-mails to those people who've taken a survey already.
**'''Filtering:''' Filter users on various suitable criteria
**'''Templates:''' Design a template system announcement beyond a simple find-and-replace. We don't want you to build the next Smarty or Django templates replacement, but dazzle the users with something cool and usable
**'''Management:''' Folders, counters,
*'''Inbox:''' Build a system that would allow users to communicate among each other without the need for e-mail. ('''Not chat''')!
**'''Message Type:''' Categorise the messages
**'''Linking with Announcements:''' Use it as an alternative to e-mail.
**'''E-mail notifications:''' Is it a good idea? How often is good? Allow people to choose if they want it?
*'''Assignments''': Assignment is how a Survey is deployed. It can be time-restricted or region-restricted etc. Make improvements on the Assignment features and its design GUI.

'''Skills'''

PHP, CakePHP, JavaScript & jQuery, Creativity, UI Design

'''Difficulty'''

Moderate

'''Probable Mentors'''

Mac Duy Hai (macduy)

==LimeSurvey 2: Template/Theme Editor - <span style='color:#FF0000'>This project has no mentor!</span>==

The idea is to develop a theme / template framework similar to one in jquery [http://jqueryui.com/themeroller/ | Jquery Theme Roller] and thus making the UI design of the surveys easier.The current template editor is based on dwoo template engine which actually loads the files exposing the css etc for us to edit, which of course require some skill set to proceed. Using this template editor we can make everything UI based and thus requiring no developer skills to edit the templates.

The overview of the modules can be seen here:

[[File:theme_roller.png]]

It’ll be implemented using Jquery to use the more advanced UI experiences.(:biggrin:)

The following mock-up will give us a better view:

Moderate[[File:theme_editor_small.png]]

'''Skills'''

PHP, CakePHP, CSS, AJAX, JavaScript & jQuery.

'''Difficulty'''

Moderate

==-LimeSurvey 2: Lime Survey Social - Facebook Application - <span style='color:#FF0000'>This project has no mentor!</span>==

The idea aims at developing a Facebook app which gives a social touch to LS 2.0. The application will be integrated in several Facebook integration points like News Feed, Applications boxes, Wall etc so that the user participation will be more. Adding a social touch can drive us more user participation and increase the popularity. The ability to control the Facebook app can be provided in the LS2.0 Admin Dashboard and also in the FB user application window with varied options.

The facebook has the following modules (we can add more. This is primary draft.)
*All Survey related core features. (Create, Edit, Delete, Administer etc)
*Gain reward points.
*Use reward points to create more surveys.
*Spread the surveys ...... and more

The idea can be extended to other social networks

[[File:fb_overview.png]]

The mock-ups :

[[File:facebook app.png]]

[[File:canvas.png]]

'''Skills'''

PHP, CakePHP, Facebook API.

'''Difficulty'''

Moderate

==LimeSurvey 2: Integration of Poll Questions <span style='color:#FF0000'>This project has no mentor!</span>==

Polls are one of the most popular and quick response getting tools once can use. Implementing polls in LS 2.0 will be an added advantage. Since every one of us know what polls are about, this idea focuses on the implementation part.

The idea is to integrate the ability to create a POLL Module in Admin dashboard, where he can administer (Create | Edit | Delete | View Responses etc) the Polls.We can even get feedback “about the survey” at the end on how the user feels by creating a custom poll (we can even redirect the user to this poll).
*Chat Bots and Polls: An another idea is to create chat bots so that whenever we create a poll, all the friends (who added the bot) of that bot will be pinged by the question followed by options. Getting an answer is very easy (Bot friends just need to type a single letter stating the answer) and its a push model which ensures the delivery to everyone (even offline).We can even extend this to deliver certain type of surveys question by question through the bot.

A simple mock-up for this:

[[File:chat.png]]
*Alternate Solution: An alternate solution provided by Mazi is clubbing this idea with the Facebook app idea. Instead of porting parts of the admin backend to facebook or other social networks we'll have options in Admin panel to "publish as: common survey |mobile device survey | facebook poll | homepage poll | ... etc " Everything will be put together at the usualm admin backend but you can choose which way(s) you want publish your survey.

We can further extend this idea by giving additional options to publish as widgets for websites and blogs etc.

'''Skills'''

PHP, CakePHP, XMPP Protocol (Knowledge of developing bots), Knowledge of Polls.

'''Difficulty'''

Moderate

==LimeSurvey 2: Survey Community Project==

Build a system for LS2 that connects to a central repository of survey resources, such as demographic questions, answer styles and templates. Integrating with a login system, allow LimeSurvey users to easily publish their work to a community resource or use other published works from the same location.

For many finding already written question texts, or standardised demographic questions would really simplify their use of a survey tool. LimeSurvey could leverage on the community spirit of an open source product and encourage users to share their own work. By integrating a "Publish to the LimeSurvey Library" button in the administration system with questions, or templates, or anything else that can be shared, LimeSurvey could develop a library of tools that simplifies Survey Creation even further.

'''Skills'''

PHP, CakePHP, Web and User Interface Design Skills

'''Difficulty'''

Moderate

'''Probable Mentors'''

Jason Cleeland (jasebo)

==LimeSurvey 2: Condition Engine==

[[File:addNewCondition1.png]]

Build a system for LS2 that will let survey administrators design, store and evaluate conditions. Conditions can be used in several features such as question branching (survey logic), assessments, quotas, ...

This projects will at least end up with:
* A working GUI to design complex conditions:
** several atomic conditions can be combined by AND or OR logical operators and will support for grouping conditions with parentheses
** an atomic condition representation can be

<syntaxhighlight lang="php" enclose="div"><left operand> <operator> <right operand></syntaxhighlight>
** an atomic condition editor will implement
*** several operators (equality, inequality, string-comparisons, numerical-comparisons, regexp),...
*** meta operators surch as 'Not displayed'
** left and right operands can be answers from previous questions, or a static values. It should be extensible so that we are able in the future to use more complex operand such as the result of a specific function (for instance the sum of some previous integer questions)
* A working DB storage backend using a string in [http://en.wikipedia.org/wiki/Reverse_Polish_Notation RPN] (Reverse Polish Notation) to describe each condition
* A first version of the evaluation of conditions for the question branching feature. This part will require interaction with other parts of the projects (Survey Engine, and DB engine).

'''Skills'''

PHP, CakePHP, JQuery and User Interface Design Skills

'''Difficulty'''

High

'''Probable Mentors'''

Thibault Le Meur (lemeur)

'''Want to know more'''

Please read the [http://docs.limesurvey.org/tiki-index.php?page=GSOC+2010+Condition+engine FAQ about this project]

=We want your ideas!=

What floats your boat? Do you have another idea that gets you excited? Discuss your ideas in our [http://www.limesurvey.org/component/option,com_fireboard/Itemid,105/func,view/catid,11/id,24710/lang,en/ forums], [https://lists.sourceforge.net/lists/listinfo/limesurvey-developers mailing lists] or at #limesurvey on irc.freenode.net.

=More Information=

==LimeSurvey Google's Summer of Code 2010==
*[http://docs.limesurvey.org/tiki-index.php?page=Limesurvey+GSoC+2010 Limesurvey GSoC 2010]

An introduction to LimeSurvey and our application for this years Google Summer of Code

==Getting Started==
*[http://docs.limesurvey.org/tiki-index.php?page=GSoC_Getting_Started How to get started with LimeSurvey's GSoC]

How to Get Started With LimeSurvey:

- setting up the development environment, coding standards, and all the other important stuff that you need to know before the real fun begins!

==Frequently Asked Questions==
* [http://socghop.appspot.com/document/show/program/google/gsoc2009/faqs Google's Summer of Code Faqs]
* [http://docs.limesurvey.org/tiki-index.php?page=GSoC_Faqs LimeSurvey's GSoC Faqs]

RemoteControl

2010-01-28T14:34:07Z

Rakete:

__TOC__

=Introduction=

LimeSurvey RemoteControl is a PHP:SOAP based Web service application.

The LSRC makes it possible for developers to control specific functionality of Limesurvey from any other Application, without beeing restricted to PHP as a Programming language.

You can start a predefined survey (change titles and things), add predefined groups or questions to this coresurvey. Activate the survey, restrict it to start and endtime, make it closed, add Participant data or just tokens when you need them (your customer just bought a book and now you want to invite him to a closed survey automatically), return the unused tokens to the main application, delete a survey, get a fieldmap for a survey, invite or remind the participants of your survey, etc...

Be aware that this piece of code was originally written to bind LimeSurvey to a University management software in order to evaluate lectures. So there could be comments in the code or documentation, which have to do with my Company's Software or which are just a little bit confusing when you have nothing to do with University's or the German language.

Post any comments, wishes or bugs to the [http://bugs.limesurvey.org bugtracker].

==Files included in LSRC==
* lsrc.config.php (configuration variables)
* lsrc.server.php (the logical SOAP:Server brain. Programm logic is mainly in here )
* lsrc.helper.php (class LsrcHelper, this Class does the work. Mainly copied and customized from Limesurvey files. Especially for import tasks)
* lsrc_orig.wsdl (wsdl definition for SOAP messages. From this file the lsrc.wsdl is generated with correct paths)
* lsrc.testclient.php (to test the environment and functionality of the webservice on the fly)

== Directory included==
* \surveys (for the core survey .csv's.) Used by sCreateSurvey.
* \groups (for exported group .csv's . Used by sImportGroup. There should be always an empty group for importing, so you can add questions to a new group)
* \questions (for exported questions .csv's. sImportFreetext and sImportMatrix depend on "Freitext.csv" and "Matrix5.csv" which should be exported questions(Freetext and Array 5 point Matrix).

== Requirements==
* PHP >= 5.2.1 with PHP:SOAP Extension enabled
* libXML installed
* MySQL, PostgreSQL or (not recommended) MSSQL
* (optional) OpenSSL
* (optional) a Certificate for better Security

=Installation=

== How to install LSRC==

'''NOTE:''' It is included in Limesurvey since 1.80RC2, before 1.80RC4 it was called "japh" or "japhService"
* create a Dir "remotecontrol" in your LimeSurvey admin dir.
* copy the included files to the new directory.

== How to configure LSRC==
* first of all you have to '''enable the LSRC in LimeSurveys config.php''' or in lsrc.config.php
** set the variable '''$enableLsrc = true''';
* In the '''lsrc.config.php''' file, you can '''set all needed Variables''' for the LSRC in Section Variables.
** set the Error Handling. While configuring and testing it is very good to get all errors. If you are using lsrc in Production, you should comment error_reporting, so that it sticks to the servers defaults.
** $lsrcDebug, if set to true, the lsrc writes an own log. This log is helpful when implementing new features, if some function does not work, look where it hangs in this log. Should be set to false if in productive Use.
** $lsrcDebugLog, File where the log should be written to.
** ini_set("log_errors", "1"), Apaches log file (error.log) will get filed with php-errors. Very useful for debugging. Comment if in productive Mode.
** ini_set("soap.wsdl_cache_enabled", "0"), while testing, caching is not useful. If in productive Mode, turn this on or just comment the line to stick to server defaults.
** (optional) set $lsrcOverSSL to true, if you want SOAP to exchange the messages over SSL resp. https. It does not more or less than generating the target address in the wsdl with http: or https:.
** set the dirs, where the .csv files to import can be found. You will have to export some survey, you want to import and activate with LSRC, first.
** (optional) change $sLsrcSeparator = "your separator"; in lsrc.config.php if you wish to separate tokens for the sInsertToken function with any other separator than default, which is a comma.
** (optional) change $sDatasetSeperator= "your separator"; in lsrc.config.php if you wish to separate Datasets for the sInsertParticipants function with any other separator than default, which are two colons.
** (optional) change $sDatafieldSeperator= "your separator"; in lsrc.config.php if you wish to separate Datafields for the sInsertParticipants function with any other separator than default, which is a semicolon.
* the script needs rights to write files to the folder "admin/remotecontrol/" (lsrc.log, if logging is used and lsrc.wsdl). if(you cannot or don't want to set the directory rights to 777){create those two files(lsrc.log and lsrc.wsdl)in the lsrc dir with the permission to write them(777))
* If you want to save Survey, group or question csv's directly from Limesurvey into the lsrc Folders, you need to set them to 777, too. (Option can be enabled by adding $export4lsrc = true; to Limesurveys config.php)
* You may have to generate a wsdl file if you need a static one. Run lsrc.server.php?wsdl and the script will make a lsrc.wsdl with the correct server url included in the lsrc directory.
* If auto wsdl generation do not work properly (maybe virtual hosts make Problems, please report back, if so or not so, can't test at the moment) You have to set the url of the lsrc.server.php script in the last block of the wsdl

==How to enable OpenSSL / https Support==
* LSRC supports SSL over http resp. https.
* Your Webserver needs to support and enable OpenSSL (See your Webserver Manual)
* '''ATTENTION:''' Just set the Variable $lsrcOverSSL = true; in lsrc.config.php. After that, initialize your client like shown below, a wsdl file with correct URL will be generated automaticly for you:

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

new SoapClient('https://localhost/limesurvey/admin/lsrc.server.php?wsdl',

array('soap_version' => SOAP_1_1,

'trace' => 1));

</syntaxhighlight>
* 'ONLY FOLLOW THIS STEPS IF WSDL GENERATION DOES NOT WORK FOR YOU' <br>There are two locations in the code, where you force the webservice to use https

<nowiki>:</nowiki> 1. On the client side, when you call the SOAP-Server over wsdl. For 'https' do it like that:

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

new SoapClient('https://localhost/limesurvey/admin/remotecontrol/lsrc.wsdl', array('soap_version' => SOAP_1_1,

'trace' => 1));

</syntaxhighlight>

<nowiki>:</nowiki> for 'http' like that:

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

new SoapClient('http://localhost/limesurvey/admin/remotecontrol/lsrc.wsdl', array('soap_version' => SOAP_1_1,

'trace' => 1));

</syntaxhighlight>

<nowiki>:</nowiki> Note that the client will only get the wsdl-definition over https, to get the SOAP Messages over https, set the uri in the wsdl file, like below...

<nowiki>:</nowiki> 2. Here is the most important Step to SSL. At the End of the lsrc.wsdl file, last block, same procedure:

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

<port name='LsrcPort' binding='tns:LsrcBinding'>

<soap:address location='https://localhost/limesurvey/admin/remotecontrol/lsrc.server.php' />

</port>

</syntaxhighlight>

<nowiki>:</nowiki> or for normal http mode:

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

<port name='LsrcPort' binding='tns:LsrcBinding'>

<soap:address location='http://localhost/limesurvey/admin/remotecontrol/lsrc.server.php' />

</port>

</syntaxhighlight>

That's it! all request, response and fault messages will be transported over https...

=How to use LSRC=

==use the client==

'''NOTE on PHP 5.3:''' setting the path2wsdl to http://localhost/limesurvey/admin/remotecontrol/lsrc.server.php?wsdl worked with all prior 5.3 version of PHP. With PHP 5.3 the client will not recognize the wsdl lsrc.server.php?wsdl gives back. You have to call lsrc.server.php?wsdl once to generate the lsrc.wsdl file and then point your client to http://localhost/limesurvey/admin/remotecontrol/lsrc.wsdl instead.

There is a PHPclient (from version 1.86) in the remotecontrol folder. You can use this ClientClass to control Limesurvey from within your PHP Applications with ease.

Take a look at lsrc.testclient-new.php to get an impression of how it can be implemented.

Basically you just have to include the class, prepare the Client and start the function calls.

Example:

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

<?php

/**
* include the client class
*/

include_once("lsrc.client.php");

/**
* initiate the testclient object
*/

$testclient = new lsrcClient();

/**
* prepare the lsrcClient class (initiate the soapClient, set sid if needed)
*/

$testclient->prepare(333);

/**
* set user and password (only needed, when not set in the client class directly)
*/

$testclient->user = 'admin';

$testclient->pass = 'password';

/**
* set the path2wsdl (only needed, when not set in the client class directly)
*/

$testclient->path2wsdl = 'http://localhost/limesurvey/admin/remotecontrol/lsrc.server.php?wsdl';

/**
* call the function to create a survey
*/

$sReturn = $testclient->createSurvey("surveyName" , "surveyDescription", "welcomeText", "endText", "surveyAdmins@email.adress", "Survey Adminsname", "http://end.url", "Description of End Url", "template138");

echo $sReturn;

</syntaxhighlight>

This Skript initiates the client. The parameter at prepare, sets the surveyId. In this case it means we are going to create the survey with the Id 333. If you do not give an id, the survey will get a random id.

Next we set the user and password to use. You do not have to do this, as long as the inital values of the client are correct. But you may have to, if you build your app in a way, that different users use the client to create Surveys or edit them.

In the end, the survey is created with the createSurvey Method and the return is echoed.

==using the functions==

You will need a SOAP- or at least RPC-Client to communicate with the LSRC Webservice. How to create such a Client depends on the programming language you use.

The LSRC itself is written in PHP5 using the PHP:SOAP extension with SOAP 1.1.

In PHP you would initiate the Client-object and call a function from the Webservice with code like e.g.:

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

$wsdl="http://localhost/limesurvey/admin/remotecontrol/lsrc.server.php?wsdl";

$client = new SoapClient($wsdl, array('soap_version' => SOAP_1_1,

'trace' => 1));

try

{

$sReturn = $client->sInsertToken($user, $pass, $iVid, $sToken);

}

catch (SoapFault $fault)

{

$sOutput .= " <br/><br/>SOAP Error: ".$fault->faultcode." : ".$fault->faultstring;

}

</syntaxhighlight>

The LSRC offers some functions:

(<span style='color:#FF0000'>m</span>) means: Mandatory Parameter

==sCreateSurvey==

<span style='color:#FF0000'>Parameters changed after 1.81+! (sVend added)</span>
* String sCreateSurvey($sUser, $sPass, $iVid, $sVtit , $sVbes, $sVwel, $sVend, $sMail, $sName, $sUrl, $sUbes, $sVtyp )
** '''Purpose''': Creates a new survey. It imports an exported survey from any LS v1.xx. and changes some fields (in the current Version it changes SurveyTitle, SurveyDescription and SurveyWelcomeText, adminemail, adminname, url and url_description to the string which was given by the client.)
** '''Parameters''':
*** (<span style='color:#FF0000'>m</span>) string USER, this have to be an existing Useraccount with appropriate rights
*** (<span style='color:#FF0000'>m</span>) string PASSWORD, this has to match the password for the account.
*** (<span style='color:#FF0000'>m</span>) int $iVid, SurveyID desired ID for the Survey, make sure it doesn't already exist in LimeSurvey
*** (<span style='color:#FF0000'>m</span>) string $sVtit, SurveyTitle, should be the (Nr +)Name of the Event to be evaluated
*** (<span style='color:#FF0000'>m</span>) string $sVbes, Survey Description, This should be String put together with veransttyp + doztitle + dozname
*** string $sVwel, Survey Welcometext, A text shown before the survey starts. If not given it says: "Herzlich Willkommen zur Evaluation von "$sVtit"
*** string $sVend, Survey Endtext, Text shown at the endpage.
*** string $sMail, Admin Email, Email Adress of the responsible person for this survey
*** string $sName, Name of the responsible person for this survey
*** string $sUrl, Url of the Link, shown on the last page of survey.
*** string $sUbes, Description String of the URL above. ( <a href='$sUrl'>$sUbes</a> )
*** string $sVtyp, The type of Event that should be evaluated. Use in combination with sAvailableModules with $mode='core' to get all available "types"
** '''Returns''':
*** if everything went fine, it returns the SurveyID from the created survey
** '''Possible Faults''':
*** throw new SoapFault("Authentication: ", "User or password wrong");
*** throw new SoapFault("Database: ", "SurveyID already exists");
*** throw new SoapFault("Server: ", "Mandatory Parameters missing");
*** throw new SoapFault("Server: ", "Import went wrong somehow");
** '''Note''':
*** Goto line 714 in lsrc.helper.php to see what can be done and customized while importing.
*** If you want Limesurvey to give your Survey a random Number if the given ID exist (because you do not need a specific identification for your surveys), just go into the function sCreateSurvey in lsrc.server.php and delete or comment out the if($lsrcHelper->surveyExists($iVid)) clause. In Result, Limesurvey will give your survey a random ID when the given ID exists.

==sActivateSurvey==
* String '''sActivateSurvey'''(string USER, string PASSWORD, int SurveyID, date start, date end)
** '''Purpose''': Activates an existing survey and set start and enddate optional
** '''Parameters''':
*** (<span style='color:#FF0000'>m</span>) string USER, this have to be an existing Useraccount with appropriate rights
*** (<span style='color:#FF0000'>m</span>) string PASSWORD, this has to match the password for the account.
*** (<span style='color:#FF0000'>m</span>) int SurveyID, the SurveyID for the Survey to activate.
*** date start, date for the Survey to start. 2008-10-22 means it starts exactly at 2008-10-22 00:00:00 Servertime
*** date end, date for the Survey to end. 2008-10-22 means it ends exactly at 2008-10-22 23:59:59 Servertime. Nobody can access nor complete the Survey only a second later.
** '''Returns''':
*** if everything went fine, it returns the SurveyID from the activated survey
** '''Possible Faults''':
*** throw new SoapFault("Authentication: ", "User or password wrong");
*** throw new SoapFault("Database: ", "Survey you want to activate does not exists");
*** throw new SoapFault("Server: ", "Mandatory Parameters missing");
*** throw new SoapFault("Server: ", "Activation went wrong somehow");
** '''Note''':
*** You can set startDate and/or endDate after activation if needed. Just run the function again with desired parameters.

==sImportGroup==
* String '''sImportGroup'''(string USER, string PASSWORD, int SurveyID, String Module, String groupName, String groupDescription)
** '''Purpose''': Imports an exported group file (.csv) to the Survey given by SurveyID
** '''Parameters''':
*** (<span style='color:#FF0000'>m</span>) string USER, this have to be an existing Useraccount with appropriate rights
*** (<span style='color:#FF0000'>m</span>) string PASSWORD, this has to match the password for the account.
*** (<span style='color:#FF0000'>m</span>) int SurveyID, the SurveyID
*** (<span style='color:#FF0000'>m</span>) string Module, the filename of the Group you want to add to the Survey. Use sAvailableModules to get the available groups.
*** string groupName, the Title the Group gets. If not set, it will use the title given in the .csv.
*** string groupDescription, Description of the group. If not set, it will use the description given in the .csv.
** '''Returns''':
*** if everything went fine, it returns the String "Import OK"
** '''Possible Faults''':
*** throw new SoapFault("Authentication: ", "User or password wrong");
*** throw new SoapFault("Authentication: ", "You have no right to change Surveys from other people");
*** throw new SoapFault("Server: ", "Survey Module $sMod does not exist");
*** throw new SoapFault("Server: ", "Group does not support Surveys Baselanguage ($langcode)");
** '''Note''':
*** It imports only exported groups as .csv which lay under \groups or any other dir given in lsrc.config.php
*** <strike>It imports only the files beginning with "mod_" ending with ".csv"</strike>
*** The Param Module must only contain the "name of the Module": Only the String before ".csv"
*** The baselanguage of the group to import, have to match the baselanguage of the coresurvey.

==sImportQuestion==
* String '''sImportQuestion'''(string USER, string PASSWORD, int SurveyID, String Module, String mandatory)
** '''Purpose''': Imports an exported question file (.csv) to the last group of the Survey given by SurveyID. This is meant for predefined questions stored in the /question directory
** '''Parameters''':
*** (<span style='color:#FF0000'>m</span>) string USER, this have to be an existing Useraccount with appropriate rights
*** (<span style='color:#FF0000'>m</span>) string PASSWORD, this has to match the password for the account.
*** (<span style='color:#FF0000'>m</span>) int SurveyID, the SurveyID
*** (<span style='color:#FF0000'>m</span>) String Module, the name of the csv file you want to add to the Survey, without extension(.csv).
*** String mandatory, default='N' set to 'Y' if you want that question mandatory
** '''Returns''':
*** if everything went fine, it returns the String "OK"
** '''Possible Faults''':
*** throw new SoapFault("Authentication: ", "User or password wrong");
*** throw new SoapFault("Authentication: ", "You have no right to change Surveys from other people");
*** throw new SoapFault("Server: ", "Group does not support Surveys Baselanguage ($langcode)");
** '''Note''':
*** It imports only exported questions as .csv which lay under \questions or any dir given in lsrc.config.php
*** The baselanguage of the question to import, have to match the baselanguage of the core survey.

==sImportFreetext==
* String '''sImportFreetext'''(string USER, string PASSWORD, int SurveyID, String questionTitle, String questionText, String questionhelp, String module='freitext', string mandatory)
** '''Purpose''': Imports an exported question file (.csv) to the last Group of the survey given by SurveyID and changes the Title, question and helptext. This is meant for importing empty question.csv's (Text Questions)
** '''Parameters''':
*** (<span style='color:#FF0000'>m</span>) string USER, this have to be an existing Useraccount with appropriate rights
*** (<span style='color:#FF0000'>m</span>) string PASSWORD, this has to match the password for the account.
*** (<span style='color:#FF0000'>m</span>) int SurveyID, the SurveyID
*** String questionTitle, Name or Categorie of the Question
*** String questionText, The Question itself
*** String questionhelp, A little Help text for better understanding of the Question
*** String module, the name of the Module you want to add to the Survey. It should be "Freitext" by default.
*** String mandatory, make the question mandatory by giving 'Y' as this param.
** '''Returns''':
*** if everything went fine, it returns the String "OK"
** '''Possible Faults''':
*** throw new SoapFault("Authentication: ", "User or password wrong");
*** throw new SoapFault("Authentication: ", "You have no right to change Surveys from other people");
*** throw new SoapFault("Server: ", "Group does not support Surveys Baselanguage ($langcode)");
** '''Note''':
*** It imports only exported questions as .csv which lay under \questions or any dir given in lsrc.config.php
*** It is meant for importing one shortext, Longtext or Hugetext Question and changing the Question and Helptext.
*** The baselanguage of the question to import, have to match the baselanguage of the core survey.
*** Be sure to have at least one proper .csv (Freitext.csv) in the proper directory (questions), to use this function.
*** Use sAvailableModules with mode='que' to get all question .csv's available.

==sImportMatrix==
* String '''sImportMatrix'''(string USER, string PASSWORD, int SurveyID, String Module, String questionText, String questionhelp, String questionItems)
** '''Purpose''': Imports an exported question file (Matrix5.csv) to the Survey given by SurveyID and changes the question, helptext and gives Items to the 5 Scale Matrix. This is meant for importing one 5 Scale Matrix Question.
** '''Parameters''':
*** (<span style='color:#FF0000'>m</span>) string USER, this have to be an existing Useraccount with appropriate rights
*** (<span style='color:#FF0000'>m</span>) string PASSWORD, this has to match the password for the account.
*** (<span style='color:#FF0000'>m</span>) int SurveyID, the SurveyID
*** string Module, the name of the Module you want to add to the Survey. It should be "Matrix" by default.
*** String questionText, the question or text to the Matrix
*** String questionhelp, the help text
*** String questionItems, the Items that should be rated, separated by commas
** '''Returns''':
*** if everything went fine, it returns the String "OK"
** '''Possible Faults''':
*** throw new SoapFault("Authentication: ", "User or password wrong");
*** throw new SoapFault("Server: ", "Group does not support Surveys Baselanguage ($langcode)");
** '''Note''':
*** It imports only exported groups as .csv which lay under docs\demosurveys\studiply_mod
*** It is meant for importing a group with only one 5 Scale Matrix Question and changing the Question and Helptext and add Items.
*** Be sure to use an user with the surveys baselanguage as default, because this language is used to fill the language fields for answers and questions while importing.

==sAvailableModules==
* String '''sAvailableModules'''(string USER, string PASSWORD, string mode)
** '''Purpose''': Returning all the csv Names of the csv's in the Directorys configured in lsrc.config.php
** '''Parameters''':
*** (<span style='color:#FF0000'>m</span>) string USER, this have to be an existing Useraccount with appropriate rights
*** (<span style='color:#FF0000'>m</span>) string PASSWORD, this has to match the password for the account.
*** String mode, (optional) "mod" for the available groups, "core" for the coreSurveys, "que" for addable questions. Default, when not given is "mod".
** '''Returns''':
*** if everything went fine, it returns a String with all surveys, groups or questions (depends on mode) in the Dir given in lsrc.config.php, separated by comma.
** '''Possible Faults''':
*** throw new SoapFault("Authentication: ", "User or password wrong");
** '''Note''':

==sSendEmail==
* String sSendEmail($sUser, $sPass, $surveyID, $type, $maxLsrcEmails='', $subject='', $emailText='')
** '''Purpose''': sends Emails to Participants of a particular survey
** '''Parameters''':
*** (<span style='color:#FF0000'>m</span>) string USER, this have to be an existing Useraccount with appropriate rights
*** (<span style='color:#FF0000'>m</span>) string PASSWORD, this has to match the password for the account.
*** (<span style='color:#FF0000'>m</span>) int surveyID, Id of the survey from which participants will be mailed
*** (<span style='color:#FF0000'>m</span>) string type, the kind of email you like to send (invite, remind or custom)
*** int $maxLsrcEmails, if you want to override $maxemails setting in config.php for sending mails with lsrc: here you go.
*** string subject, only needed if type==custom, the subject for the mail to be send.
*** string emailText, only needed if type==custom, the text for the mail to be send.
** '''Returns''':
*** "X Mails send" or "No Mails to send" in custom mode.
*** "X Mails send. X Mails left to send" or "No Mails to send" in invite mode.
*** "X Reminders send. X Reminders left to send" or "No Reminders to send" in remind mode.
** '''Possible Faults''':
*** throw new SoapFault("Authentication: ", "User or password wrong");
*** throw new SoapFault("Server: ", "Mandatory Parameters missing");
*** throw new SoapFault("Type: ", "Wrong send Type given. Possible types are: custom, invite or remind");
** '''Note''':
*** invite: When $maxemails is set the function sends only $maxemails in one go. If you call it again, it will go on to send the invitations, until everyone is invited.
*** remind: When $maxemails is set, it will only send $maxemails in one go. It checks if reminders have been send to other participants and if there are participants who received less reminders than others, the script will first send reminders to those who have not been reminded so often, until the remindercount is equal.
*** custom: $maxemails have no effect in custom mode. I have no solution for counting those who have been mailed before.

==sInsertToken==
* String '''sInsertToken'''(string USER, string PASSWORD, int SurveyID, string Token)
** '''Purpose''': Creates and populates a table {dbprefix}token_{SurveyID} and thus "closes" the survey. It is possible to add tokens to the existing table.
** '''Parameters''':
*** (<span style='color:#FF0000'>m</span>) int SurveyID, ID of the survey to close with a token table
*** string Token, a string with comma separated tokens. There is a possibility to set any other separator in config.php. Max. tested length of a string was 500,000 tokens, that makes a String of 5,500,000 Chars, this is just the limit of the apache webserver on my notebook (CoreDuo 1,6MHz, 1GB Ram) with default Resource Limits (60,60,16). I recommend to send max. 100,000 tokens over the webservice. Repeat for more tokens.
*** (<span style='color:#FF0000'>m</span>) string USER, this have to be an existing Admin-, Superadmin- or Useraccount with the rights to create and activate Surveys
*** (<span style='color:#FF0000'>m</span>) string PASSWORD, this has to match the password for the account.
** '''Returns''':
*** if everything went ok, it returns the String: "[X] Token given, [X] Token inserted"
** '''Possible Faults''':
*** throw new SoapFault("Authentication: ", "User or password wrong");
*** throw new SoapFault("Database: ", "Survey does not exists");
*** throw new SoapFault("Server: ", "Token could not be inserted");
** '''Note''':
*** Make sure on the client side that no token appears twice in the table. There is no check on this and won't be in the future. What happens if there are two same tokens? 2 participants will get the same token, one will fill out the form for both, and the other will get a message: "your token have already participated"
*** If there is no token table, it will create one and add the tokens.
*** If the Tokentable already exists, it just adds the given tokens to the existing table.

==sInsertParticipants==
* String '''sInsertParticipants'''(string USER, string PASSWORD, int SurveyID, string ParticipantData)
** '''Purpose''': Creates and populates a table {dbprefix}token_{SurveyID} and thus "closes" the survey. You can deliver some data to the token table. If you do not support a token, or an empty String as token, a unique token will be generated for the participant.
** '''Parameters''':
*** (<span style='color:#FF0000'>m</span>) int SurveyID, ID of the survey to close with a token table
*** string ParticipantData, The Data have to be in the right Syntax, it's like this:

<pre>

FIRSTNAME;LASTNAME;EMAIL;ATTRIB1;ATTRIB2;TOKEN::FIRSTNAME;LASTNAME;EMAIL;ATTRIB1;ATTRIB2;TOKEN

</pre>

'''NOTE: The Data Syntax change with 1.86'''. in order to take language, validfrom, validuntil and a variable count of attributes.

With 1.86 and later versions, it will have to be like this:

<pre>

FIRSTNAME;LASTNAME;EMAIL;LANGUAGE;TOKEN;VALIDFROM;VALIDUNTIL;attribute1,attribute2,attribute3::FIRSTNAME ... etc.

</pre>

note that the 8th field is the attributes field. There is no 9th field. You can seperate many attributes with a colon (,). The lsrc will create the needed fields in the db if they are not present. All Fields after LANGUAGE are optional and do not have to be send.

seperate the Datasets with double colons (::) and the fields with semicolon (;). The '''attrib1, attrib2 and token fields are optional''', you can just leave them out if not used. Note that the attrib field will get empty and not NULL, by now there where no complications, inform us, if you see some difficulties in not setting them NULL. Max. successfully tested length of a string was 3,000,000 Chars, this is just the limit of the apache webserver on my notebook (CoreDuo 1,6MHz, 1GB Ram) with default Resource Limits (60,60,16). I recommend to send max. 10,000 Datasets over the webservice at once(~1,000,000 chars). Repeat for more Datasets.
*** (<span style='color:#FF0000'>m</span>) string USER, this have to be an existing Admin-, Superadmin- or Useraccount with the rights to create and activate Surveys
*** (<span style='color:#FF0000'>m</span>) string PASSWORD, this has to match the password for the account.
** '''Returns''':
*** if everything went ok, it returns the String: "[X] Datasets given, [X] rows inserted. ";
** '''Possible Faults''':
*** throw new SoapFault("Authentication: ", "User or password wrong");
*** throw new SoapFault("Server: ", "No SurveyId given");
*** throw new SoapFault("Database: ", "Survey does not exists");
** '''Note''':
*** default tokenlength is 5 chars, if you want to change the length, goto lsrc.server.php, line 441
*** If the token table does not exists, it will be created, and if it does, the data will be added.

==sTokenReturn==
* string return '''sTokenReturn'''(string USER, string PASSWORD, int SurveyID)
** '''Purpose''': Gives back all Tokens, which did not complete the Survey, in a String seperated by commas.
** '''Parameters''':
*** (<span style='color:#FF0000'>m</span>) int SurveyID, the ID for the Survey from which you want get the unused tokens
*** (<span style='color:#FF0000'>m</span>) string USER, this have to be an existing Admin-, Superadmin- or Useraccount with the rights to create and activate Surveys
*** (<span style='color:#FF0000'>m</span>) string PASSWORD, this has to match the password for the account.
** '''Returns''':
*** Returns a String, a string of all unused tokens seperated by comma.
** '''Possible Faults''':
*** throw new SoapFault("Authentication: ", "User or password wrong");
*** throw new SoapFault("Database: ", "Survey does not exists");
*** throw new SoapFault("Server: ", "No SurveyId given");
*** throw new SoapFault("Database: ", "Token table for this Survey does not exists");
*** throw new SoapFault("Database: ", "No unused Tokens found");

==sGetFieldmap==
* string return '''sGetFieldmap'''(string USER, string PASSWORD, int SurveyID)
** '''Purpose''': Gives back the fieldmap for the survey

for example:

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

"fieldname","type","sid","gid","qid","aid","title","question","group_name","lid","lid1"

"111X779X39801","F","111","779","3980","1","1","How do you feel?","Paticipant feelings","",""

"111X779X39802","M","111","779","3980","2","1a","Why do you feel like this?","Paticipant feelings","",""

[...]

</syntaxhighlight>
** '''Parameters''':
*** (<span style='color:#FF0000'>m</span>) int SurveyID, the ID for the Survey from which you want to get the Fieldmap.
*** (<span style='color:#FF0000'>m</span>) string USER, this have to be an existing Admin-, Superadmin- or Useraccount with the rights to create and activate Surveys
*** (<span style='color:#FF0000'>m</span>) string PASSWORD, this has to match the password for the account.
** '''Returns''':
*** Returns a String, a string of the fieldmap, seperated by comma and blanks
** '''Possible Faults''':
*** throw new SoapFault("Authentication: ", "User or password wrong");
*** throw new SoapFault("Authentication: ", "You have no right to get fieldmaps from other peoples Surveys");
*** throw new SoapFault("Database: ", "Survey does not exists");
*** throw new SoapFault("Server: ", "No SurveyId given");

==fSendStatistic==

<span style='color:#FF0000'>''(since 1.86)''</span>
* '''fSendStatistic'''(string USER, string PASSWORD, int SurveyID, string Email, string doctype, string graph)
** '''Purpose''': sends an Statistic File as Attachment
** '''Parameters'''
*** user: Limesurvey user
*** password: Limesurvey Password
*** surveyId: ID of the survey from which statistics should be generated
*** email: the adress to which the statistic file is send
*** doctype: pdf, xls or html. With pdf or xls, the recipient gets an attached file with a short notice. With html, he gets an html e-mail without attachments
*** graph: turn graph generation on or off. Works only with pdf generation. Use '1' as a string if you want to enable it
** '''returns'''
*** string: 'XLS send'
*** string: 'PDF send'
*** string: 'HTML send'
** '''possible Faults'''
*** throw new SoapFault("Server: ", "Mandatory Parameters missing");
*** throw new SoapFault("Authentication: ", "User or password wrong");
*** throw new SoapFault("Authentication: ", "You have no right to send statistics from other peoples Surveys");
*** throw new SoapFault("Database: ", "Survey does not exists");
*** throw new SoapFault("Mail System", "Mail could not be send! Check your E-Mail Settings.");

=Testing=

For testing purposes, we made a testclient in php. Therefore you need a webserver to run it. If you test on one machine you need nothing to do, you can go to http://localhost/limesurvey/admin/lsrc/lsrc.testclient.php in your browser to test the webservices functionality.

Of Course this is very boring, because the apache talks with himself (and thats not the matter of a webservice).

The Testclient have two purposes:

1. It checks the Server(the one the testclient is running on!) for the PHP:SOAP Extension and installed libXML version and gives feedback if the enviroment does support SOAP via PHP:SOAP. This is very useful to check your Server and your Client towards PHP:SOAP compatibility. In addition to this, it will check if the wsdl file you want to connect to exists, it does not validate the wsdl file.

2. You can test the functions of the webservice.

If you test the webservice in realistic enviroment (two machines) you have to customize three things
* the lsrc.testclient.php needs to be on the machine where the webservice is NOT running, but it needs a webserver... download xampp from apachefriends if you dont have one <strike>(caution for Linux Users: you have to compile PHP5 with SOAP and enable the extension, futhermore you have to install libXML2. Last thing can by done very easy via Synaptics or apt-get)</strike> xampp for Linux works well with SOAP and libXML from version 1.7.
* this Line:

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

$limeUrl='https://localhost/limesource/limesurvey';

</syntaxhighlight>

At the beginning of lsrc.testclient.php needs to fit the target Limesurvey Installation Dir. localhost for servername is always wrong in this testcase, 127.0.0.1, too.

'''NOTES''':
* The Testclient is configured to use "admin" "password" as authentication. If you want to test with another user or password you have to set this vars in lsrc.testclient.php ( lines 40 and 41)
* If you just get a blank page on the testclient, make sure the path to the wsdl is correct, and the var $enableLsrc is set to true in config.php or lsrc.config.php

=Notes=
* Security is enhanced: no action without permission (as good as Limesurveys Security itself --> very good)
* No headers or "Quick and Dirtys" anymore, no Scripts, just functions and a class.
* All configuration Variables are stored in lsrc.config.php by now
* There is a debug functionality, showing where the script runs through the code in an own log file. Use Apaches error.log in addition to find errors if you got any.
* LSRC is part of LimeSurvey, therefore it stands under GNU/GPL License v2 or later.
* SOAP Services and therefore LSRC only support UTF-8 charsets.
* LSRC works with AdoDB (MySql,Postgresql, MSSQL) .
* LSRC is tested, but under steady development, use on your own risk, test the functions before using them productively!

=Changes=

1.86
* new function fSendStatistics: to send statistics as attachment to an e-mail-address
* Datasyntax for sInsertParticipants changed in order to take validfrom, validuntil, language and a variable Set of attributes.

1.85
* Several improvements to stability.

1.82
* Added sVend Parameter to sCreateSurvey, to set the endtext
* sInsertParticipants takes a token in the dataset, however, if non is supported, it will be generated.
* a new variable $enableLsrc is introduced to enable the Lsrc only when it is used.
* a serious exploit has been fixed.

1.81
* Added sGetFieldmap function.
* The template.csv's changed.
* exported csv's prior 1.81 will not import over lsrc anymore. Import them via Browser and export them back to lsrc.

1.80 => 1.81
* Changed sImportGroup: imports '''all''' groups under $modDir, adds them to the survey. Not only the ones with mod_ as prefix. In addition, you can give Name and Description of the Group.
* New sImportQuestion: imports questions in $queDir and adds them to the last group
* New sImportFreetext: imports a Freetext question and changes the title and question to the Strings given. Previously, this function was called sImportQuestion.
* Changed sAvailableModules: type can be core, mod or que. "que" is new and gives back the names of all the questions available.
* New sSendEmail: send invitations, reminders and custom mails to participants of a survey over Limesurvey.

=ToDo / ToCome=
* <strike>sInsertParticipants should take a lang attribute for each participant</strike>

please add your feature requests to the [http://bugs.limesurvey.org bugtracker] if it is not listed here...

=Known Bugs (and workarounds)=
* With PHP 5.3.0, the testclient have problems to read the generated wsdl from lsrc.server.php?wsdl. You have to generate it an use the static file to test it.
* Surveys get not imported in 1.85, due to a bug. The bug is fixed and will be released with the next release. Talk to rakete if you need it earlier...
* exported csv's prior 1.81 will not import over lsrc anymore. Import them via Browser and export them back to lsrc to get them work again. (attributes moved from survey to survey_languagesettings)
* sInsertPaticipants and sInsertToken function: You should note, that in case of an Seperator at the beginning or the end of the Datastring, the return Message will recognize one more given Dataset or Token as inserted into the db...
* There is a bug with Webservices in general: Sometimes (~ 1 of 10.000 Cases) you will get an error message like "function 'anyFunction' does not exist on the server" or similar, altough everything is fine. Just wait a few Moments, clear you cache, phone your mom (she will be happy to hear from you ;)) and try again.
* Webservice will not work if the "install" dir is not renamed or deleted in limesurvey and $debug is not set to 2 -> "looks like we got no xml document" without errorlogs

please add your bug report to the [http://bugs.limesurvey.org bugtracker] if you found an Issue that is not listed here.

=Security=

There have been a security hole in the versions prior 1.82 (1.80RC2 to 1.81+). This leak could be used to compromise your webspace if it is weakly configured.

To minimise the risk of a security leak endanger your system, we disabled the lsrc by default with version 1.82 and you have to enable it explicity in your config.php.

Some things you can do to improve your security when using the lsrc:
* instead of setting the remotecontrol folder to 777, just create an empty file lsrc.wsdl with the rights 777
* disable the lsrc.log in lsrc.config.php
* Do not set the survey, groups, questions folders to 777 for saving lsrc templates directly within Limesurvey, instead, save the .csv on your local PC and upload them via ftp to the folders.
* delete lsrc.testclient.php, when in productive use. Lsrc.testclient.php could be used from unauthorized people to perform portscanning on other machines. The attacked webserver would be seeing your webserver as attacker, altough you did not perform any attack by yourself. This is not so serious, as this bahaviour of the testclient is not much valuable for any serious hacker.

RemoteControl

2009-11-27T12:19:34Z

Rakete:

__TOC__

=Introduction=

LimeSurvey RemoteControl is a PHP:SOAP based Web service application.

The LSRC makes it possible for developers to control specific functionality of Limesurvey from any other Application, without beeing restricted to PHP as a Programming language.

You can start a predefined survey (change titles and things), add predefined groups or questions to this coresurvey. Activate the survey, restrict it to start and endtime, make it closed, add Participant data or just tokens when you need them (your customer just bought a book and now you want to invite him to a closed survey automatically), return the unused tokens to the main application, delete a survey, get a fieldmap for a survey, invite or remind the participants of your survey, etc...

Be aware that this piece of code was originally written to bind LimeSurvey to a University management software in order to evaluate lectures. So there could be comments in the code or documentation, which have to do with my Company's Software or which are just a little bit confusing when you have nothing to do with University's or the German language.

Post any comments, wishes or bugs to the [http://bugs.limesurvey.org bugtracker].

==Files included in LSRC==
* lsrc.config.php (configuration variables)
* lsrc.server.php (the logical SOAP:Server brain. Programm logic is mainly in here )
* lsrc.helper.php (class LsrcHelper, this Class does the work. Mainly copied and customized from Limesurvey files. Especially for import tasks)
* lsrc_orig.wsdl (wsdl definition for SOAP messages. From this file the lsrc.wsdl is generated with correct paths)
* lsrc.testclient.php (to test the environment and functionality of the webservice on the fly)

== Directory included==
* \surveys (for the core survey .csv's.) Used by sCreateSurvey.
* \groups (for exported group .csv's . Used by sImportGroup. There should be always an empty group for importing, so you can add questions to a new group)
* \questions (for exported questions .csv's. sImportFreetext and sImportMatrix depend on "Freitext.csv" and "Matrix5.csv" which should be exported questions(Freetext and Array 5 point Matrix).

== Requirements==
* PHP >= 5.2.1 with PHP:SOAP Extension enabled
* libXML installed
* MySQL, PostgreSQL or (not recommended) MSSQL
* (optional) OpenSSL
* (optional) a Certificate for better Security

=Installation=

== How to install LSRC==

'''NOTE:''' It is included in Limesurvey since 1.80RC2, before 1.80RC4 it was called "japh" or "japhService"
* create a Dir "remotecontrol" in your LimeSurvey admin dir.
* copy the included files to the new directory.

== How to configure LSRC==
* first of all you have to '''enable the LSRC in LimeSurveys config.php''' or in lsrc.config.php
** set the variable '''$enableLsrc = true''';
* In the '''lsrc.config.php''' file, you can '''set all needed Variables''' for the LSRC in Section Variables.
** set the Error Handling. While configuring and testing it is very good to get all errors. If you are using lsrc in Production, you should comment error_reporting, so that it sticks to the servers defaults.
** $lsrcDebug, if set to true, the lsrc writes an own log. This log is helpful when implementing new features, if some function does not work, look where it hangs in this log. Should be set to false if in productive Use.
** $lsrcDebugLog, File where the log should be written to.
** ini_set("log_errors", "1"), Apaches log file (error.log) will get filed with php-errors. Very useful for debugging. Comment if in productive Mode.
** ini_set("soap.wsdl_cache_enabled", "0"), while testing, caching is not useful. If in productive Mode, turn this on or just comment the line to stick to server defaults.
** (optional) set $lsrcOverSSL to true, if you want SOAP to exchange the messages over SSL resp. https. It does not more or less than generating the target address in the wsdl with http: or https:.
** set the dirs, where the .csv files to import can be found. You will have to export some survey, you want to import and activate with LSRC, first.
** (optional) change $sLsrcSeparator = "your separator"; in lsrc.config.php if you wish to separate tokens for the sInsertToken function with any other separator than default, which is a comma.
** (optional) change $sDatasetSeperator= "your separator"; in lsrc.config.php if you wish to separate Datasets for the sInsertParticipants function with any other separator than default, which are two colons.
** (optional) change $sDatafieldSeperator= "your separator"; in lsrc.config.php if you wish to separate Datafields for the sInsertParticipants function with any other separator than default, which is a semicolon.
* the script needs rights to write files to the folder "admin/remotecontrol/" (lsrc.log, if logging is used and lsrc.wsdl). if(you cannot or don't want to set the directory rights to 777){create those two files(lsrc.log and lsrc.wsdl)in the lsrc dir with the permission to write them(777))
* If you want to save Survey, group or question csv's directly from Limesurvey into the lsrc Folders, you need to set them to 777, too. (Option can be enabled by adding $export4lsrc = true; to Limesurveys config.php)
* You may have to generate a wsdl file if you need a static one. Run lsrc.server.php?wsdl and the script will make a lsrc.wsdl with the correct server url included in the lsrc directory.
* If auto wsdl generation do not work properly (maybe virtual hosts make Problems, please report back, if so or not so, can't test at the moment) You have to set the url of the lsrc.server.php script in the last block of the wsdl

==How to enable OpenSSL / https Support==
* LSRC supports SSL over http resp. https.
* Your Webserver needs to support and enable OpenSSL (See your Webserver Manual)
* '''ATTENTION:''' Just set the Variable $lsrcOverSSL = true; in lsrc.config.php. After that, initialize your client like shown below, a wsdl file with correct URL will be generated automaticly for you:

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

new SoapClient('https://localhost/limesurvey/admin/lsrc.server.php?wsdl',

array('soap_version' => SOAP_1_1,

'trace' => 1));

</syntaxhighlight>
* 'ONLY FOLLOW THIS STEPS IF WSDL GENERATION DOES NOT WORK FOR YOU' <br>There are two locations in the code, where you force the webservice to use https

<nowiki>:</nowiki> 1. On the client side, when you call the SOAP-Server over wsdl. For 'https' do it like that:

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

new SoapClient('https://localhost/limesurvey/admin/remotecontrol/lsrc.wsdl', array('soap_version' => SOAP_1_1,

'trace' => 1));

</syntaxhighlight>

<nowiki>:</nowiki> for 'http' like that:

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

new SoapClient('http://localhost/limesurvey/admin/remotecontrol/lsrc.wsdl', array('soap_version' => SOAP_1_1,

'trace' => 1));

</syntaxhighlight>

<nowiki>:</nowiki> Note that the client will only get the wsdl-definition over https, to get the SOAP Messages over https, set the uri in the wsdl file, like below...

<nowiki>:</nowiki> 2. Here is the most important Step to SSL. At the End of the lsrc.wsdl file, last block, same procedure:

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

<port name='LsrcPort' binding='tns:LsrcBinding'>

<soap:address location='https://localhost/limesurvey/admin/remotecontrol/lsrc.server.php' />

</port>

</syntaxhighlight>

<nowiki>:</nowiki> or for normal http mode:

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

<port name='LsrcPort' binding='tns:LsrcBinding'>

<soap:address location='http://localhost/limesurvey/admin/remotecontrol/lsrc.server.php' />

</port>

</syntaxhighlight>

That's it! all request, response and fault messages will be transported over https...

=How to use LSRC=

==use the client==

'''NOTE on PHP 5.3:''' setting the path2wsdl to http://localhost/limesurvey/admin/remotecontrol/lsrc.server.php?wsdl worked with all prior 5.3 version of PHP. With PHP 5.3 the client will not recognize the wsdl lsrc.server.php?wsdl gives back. You have to call lsrc.server.php?wsdl once to generate the lsrc.wsdl file and then point your client to http://localhost/limesurvey/admin/remotecontrol/lsrc.wsdl instead.

There is a PHPclient (from version 1.86) in the remotecontrol folder. You can use this ClientClass to control Limesurvey from within your PHP Applications with ease.

Take a look at lsrc.testclient-new.php to get an impression of how it can be implemented.

Basically you just have to include the class, prepare the Client and start the function calls.

Example:

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

<?php

/**
* include the client class
*/

include_once("lsrc.client.php");

/**
* initiate the testclient object
*/

$testclient = new lsrcClient();

/**
* prepare the lsrcClient class (initiate the soapClient, set sid if needed)
*/

$testclient->prepare(333);

/**
* set user and password (only needed, when not set in the client class directly)
*/

$testclient->user = 'admin';

$testclient->pass = 'password';

/**
* set the path2wsdl (only needed, when not set in the client class directly)
*/

$testclient->path2wsdl = 'http://localhost/limesurvey/admin/remotecontrol/lsrc.server.php?wsdl';

/**
* call the function to create a survey
*/

$sReturn = $testclient->createSurvey("surveyName" , "surveyDescription", "welcomeText", "endText", "surveyAdmins@email.adress", "Survey Adminsname", "http://end.url", "Description of End Url", "template138");

echo $sReturn;

</syntaxhighlight>

This Skript initiates the client. The parameter at prepare, sets the surveyId. In this case it means we are going to create the survey with the Id 333. If you do not give an id, the survey will get a random id.

Next we set the user and password to use. You do not have to do this, as long as the inital values of the client are correct. But you may have to, if you build your app in a way, that different users use the client to create Surveys or edit them.

In the end, the survey is created with the createSurvey Method and the return is echoed.

==using the functions==

You will need a SOAP- or at least RPC-Client to communicate with the LSRC Webservice. How to create such a Client depends on the programming language you use.

The LSRC itself is written in PHP5 using the PHP:SOAP extension with SOAP 1.1.

In PHP you would initiate the Client-object and call a function from the Webservice with code like e.g.:

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

$wsdl="http://localhost/limesurvey/admin/remotecontrol/lsrc.server.php?wsdl";

$client = new SoapClient($wsdl, array('soap_version' => SOAP_1_1,

'trace' => 1));

try

{

$sReturn = $client->sInsertToken($user, $pass, $iVid, $sToken);

}

catch (SoapFault $fault)

{

$sOutput .= " <br/><br/>SOAP Error: ".$fault->faultcode." : ".$fault->faultstring;

}

</syntaxhighlight>

The LSRC offers some functions:

(<span style='color:#FF0000'>m</span>) means: Mandatory Parameter

==sCreateSurvey==

<span style='color:#FF0000'>Parameters changed after 1.81+! (sVend added)</span>
* String sCreateSurvey($sUser, $sPass, $iVid, $sVtit , $sVbes, $sVwel, $sVend, $sMail, $sName, $sUrl, $sUbes, $sVtyp )
** '''Purpose''': Creates a new survey. It imports an exported survey from any LS v1.xx. and changes some fields (in the current Version it changes SurveyTitle, SurveyDescription and SurveyWelcomeText, adminemail, adminname, url and url_description to the string which was given by the client.)
** '''Parameters''':
*** (<span style='color:#FF0000'>m</span>) string USER, this have to be an existing Useraccount with appropriate rights
*** (<span style='color:#FF0000'>m</span>) string PASSWORD, this has to match the password for the account.
*** (<span style='color:#FF0000'>m</span>) int $iVid, SurveyID desired ID for the Survey, make sure it doesn't already exist in LimeSurvey
*** (<span style='color:#FF0000'>m</span>) string $sVtit, SurveyTitle, should be the (Nr +)Name of the Event to be evaluated
*** (<span style='color:#FF0000'>m</span>) string $sVbes, Survey Description, This should be String put together with veransttyp + doztitle + dozname
*** string $sVwel, Survey Welcometext, A text shown before the survey starts. If not given it says: "Herzlich Willkommen zur Evaluation von "$sVtit"
*** string $sVend, Survey Endtext, Text shown at the endpage.
*** string $sMail, Admin Email, Email Adress of the responsible person for this survey
*** string $sName, Name of the responsible person for this survey
*** string $sUrl, Url of the Link, shown on the last page of survey.
*** string $sUbes, Description String of the URL above. ( <a href='$sUrl'>$sUbes</a> )
*** string $sVtyp, The type of Event that should be evaluated. Use in combination with sAvailableModules with $mode='core' to get all available "types"
** '''Returns''':
*** if everything went fine, it returns the SurveyID from the created survey
** '''Possible Faults''':
*** throw new SoapFault("Authentication: ", "User or password wrong");
*** throw new SoapFault("Database: ", "SurveyID already exists");
*** throw new SoapFault("Server: ", "Mandatory Parameters missing");
*** throw new SoapFault("Server: ", "Import went wrong somehow");
** '''Note''':
*** Goto line 714 in lsrc.helper.php to see what can be done and customized while importing.
*** If you want Limesurvey to give your Survey a random Number if the given ID exist (because you do not need a specific identification for your surveys), just go into the function sCreateSurvey in lsrc.server.php and delete or comment out the if($lsrcHelper->surveyExists($iVid)) clause. In Result, Limesurvey will give your survey a random ID when the given ID exists.

==sActivateSurvey==
* String '''sActivateSurvey'''(string USER, string PASSWORD, int SurveyID, date start, date end)
** '''Purpose''': Activates an existing survey and set start and enddate optional
** '''Parameters''':
*** (<span style='color:#FF0000'>m</span>) string USER, this have to be an existing Useraccount with appropriate rights
*** (<span style='color:#FF0000'>m</span>) string PASSWORD, this has to match the password for the account.
*** (<span style='color:#FF0000'>m</span>) int SurveyID, the SurveyID for the Survey to activate.
*** date start, date for the Survey to start. 2008-10-22 means it starts exactly at 2008-10-22 00:00:00 Servertime
*** date end, date for the Survey to end. 2008-10-22 means it ends exactly at 2008-10-22 23:59:59 Servertime. Nobody can access nor complete the Survey only a second later.
** '''Returns''':
*** if everything went fine, it returns the SurveyID from the activated survey
** '''Possible Faults''':
*** throw new SoapFault("Authentication: ", "User or password wrong");
*** throw new SoapFault("Database: ", "Survey you want to activate does not exists");
*** throw new SoapFault("Server: ", "Mandatory Parameters missing");
*** throw new SoapFault("Server: ", "Activation went wrong somehow");
** '''Note''':
*** You can set startDate and/or endDate after activation if needed. Just run the function again with desired parameters.

==sImportGroup==
* String '''sImportGroup'''(string USER, string PASSWORD, int SurveyID, String Module, String groupName, String groupDescription)
** '''Purpose''': Imports an exported group file (.csv) to the Survey given by SurveyID
** '''Parameters''':
*** (<span style='color:#FF0000'>m</span>) string USER, this have to be an existing Useraccount with appropriate rights
*** (<span style='color:#FF0000'>m</span>) string PASSWORD, this has to match the password for the account.
*** (<span style='color:#FF0000'>m</span>) int SurveyID, the SurveyID
*** (<span style='color:#FF0000'>m</span>) string Module, the filename of the Group you want to add to the Survey. Use sAvailableModules to get the available groups.
*** string groupName, the Title the Group gets. If not set, it will use the title given in the .csv.
*** string groupDescription, Description of the group. If not set, it will use the description given in the .csv.
** '''Returns''':
*** if everything went fine, it returns the String "Import OK"
** '''Possible Faults''':
*** throw new SoapFault("Authentication: ", "User or password wrong");
*** throw new SoapFault("Authentication: ", "You have no right to change Surveys from other people");
*** throw new SoapFault("Server: ", "Survey Module $sMod does not exist");
*** throw new SoapFault("Server: ", "Group does not support Surveys Baselanguage ($langcode)");
** '''Note''':
*** It imports only exported groups as .csv which lay under \groups or any other dir given in lsrc.config.php
*** <strike>It imports only the files beginning with "mod_" ending with ".csv"</strike>
*** The Param Module must only contain the "name of the Module": Only the String before ".csv"
*** The baselanguage of the group to import, have to match the baselanguage of the coresurvey.

==sImportQuestion==
* String '''sImportQuestion'''(string USER, string PASSWORD, int SurveyID, String Module, String mandatory)
** '''Purpose''': Imports an exported question file (.csv) to the last group of the Survey given by SurveyID. This is meant for predefined questions stored in the /question directory
** '''Parameters''':
*** (<span style='color:#FF0000'>m</span>) string USER, this have to be an existing Useraccount with appropriate rights
*** (<span style='color:#FF0000'>m</span>) string PASSWORD, this has to match the password for the account.
*** (<span style='color:#FF0000'>m</span>) int SurveyID, the SurveyID
*** (<span style='color:#FF0000'>m</span>) String Module, the name of the csv file you want to add to the Survey, without extension(.csv).
*** String mandatory, default='N' set to 'Y' if you want that question mandatory
** '''Returns''':
*** if everything went fine, it returns the String "OK"
** '''Possible Faults''':
*** throw new SoapFault("Authentication: ", "User or password wrong");
*** throw new SoapFault("Authentication: ", "You have no right to change Surveys from other people");
*** throw new SoapFault("Server: ", "Group does not support Surveys Baselanguage ($langcode)");
** '''Note''':
*** It imports only exported questions as .csv which lay under \questions or any dir given in lsrc.config.php
*** The baselanguage of the question to import, have to match the baselanguage of the core survey.

==sImportFreetext==
* String '''sImportFreetext'''(string USER, string PASSWORD, int SurveyID, String questionTitle, String questionText, String questionhelp, String module='freitext', string mandatory)
** '''Purpose''': Imports an exported question file (.csv) to the last Group of the survey given by SurveyID and changes the Title, question and helptext. This is meant for importing empty question.csv's (Text Questions)
** '''Parameters''':
*** (<span style='color:#FF0000'>m</span>) string USER, this have to be an existing Useraccount with appropriate rights
*** (<span style='color:#FF0000'>m</span>) string PASSWORD, this has to match the password for the account.
*** (<span style='color:#FF0000'>m</span>) int SurveyID, the SurveyID
*** String questionTitle, Name or Categorie of the Question
*** String questionText, The Question itself
*** String questionhelp, A little Help text for better understanding of the Question
*** String module, the name of the Module you want to add to the Survey. It should be "Freitext" by default.
*** String mandatory, make the question mandatory by giving 'Y' as this param.
** '''Returns''':
*** if everything went fine, it returns the String "OK"
** '''Possible Faults''':
*** throw new SoapFault("Authentication: ", "User or password wrong");
*** throw new SoapFault("Authentication: ", "You have no right to change Surveys from other people");
*** throw new SoapFault("Server: ", "Group does not support Surveys Baselanguage ($langcode)");
** '''Note''':
*** It imports only exported questions as .csv which lay under \questions or any dir given in lsrc.config.php
*** It is meant for importing one shortext, Longtext or Hugetext Question and changing the Question and Helptext.
*** The baselanguage of the question to import, have to match the baselanguage of the core survey.
*** Be sure to have at least one proper .csv (Freitext.csv) in the proper directory (questions), to use this function.
*** Use sAvailableModules with mode='que' to get all question .csv's available.

==sImportMatrix==
* String '''sImportMatrix'''(string USER, string PASSWORD, int SurveyID, String Module, String questionText, String questionhelp, String questionItems)
** '''Purpose''': Imports an exported question file (Matrix5.csv) to the Survey given by SurveyID and changes the question, helptext and gives Items to the 5 Scale Matrix. This is meant for importing one 5 Scale Matrix Question.
** '''Parameters''':
*** (<span style='color:#FF0000'>m</span>) string USER, this have to be an existing Useraccount with appropriate rights
*** (<span style='color:#FF0000'>m</span>) string PASSWORD, this has to match the password for the account.
*** (<span style='color:#FF0000'>m</span>) int SurveyID, the SurveyID
*** string Module, the name of the Module you want to add to the Survey. It should be "Matrix" by default.
*** String questionText, the question or text to the Matrix
*** String questionhelp, the help text
*** String questionItems, the Items that should be rated, separated by commas
** '''Returns''':
*** if everything went fine, it returns the String "OK"
** '''Possible Faults''':
*** throw new SoapFault("Authentication: ", "User or password wrong");
*** throw new SoapFault("Server: ", "Group does not support Surveys Baselanguage ($langcode)");
** '''Note''':
*** It imports only exported groups as .csv which lay under docs\demosurveys\studiply_mod
*** It is meant for importing a group with only one 5 Scale Matrix Question and changing the Question and Helptext and add Items.
*** Be sure to use an user with the surveys baselanguage as default, because this language is used to fill the language fields for answers and questions while importing.

==sAvailableModules==
* String '''sAvailableModules'''(string USER, string PASSWORD, string mode)
** '''Purpose''': Returning all the csv Names of the csv's in the Directorys configured in lsrc.config.php
** '''Parameters''':
*** (<span style='color:#FF0000'>m</span>) string USER, this have to be an existing Useraccount with appropriate rights
*** (<span style='color:#FF0000'>m</span>) string PASSWORD, this has to match the password for the account.
*** String mode, (optional) "mod" for the available groups, "core" for the coreSurveys, "que" for addable questions. Default, when not given is "mod".
** '''Returns''':
*** if everything went fine, it returns a String with all surveys, groups or questions (depends on mode) in the Dir given in lsrc.config.php, separated by comma.
** '''Possible Faults''':
*** throw new SoapFault("Authentication: ", "User or password wrong");
** '''Note''':

==sSendEmail==
* String sSendEmail($sUser, $sPass, $surveyID, $type, $maxLsrcEmails='', $subject='', $emailText='')
** '''Purpose''': sends Emails to Participants of a particular survey
** '''Parameters''':
*** (<span style='color:#FF0000'>m</span>) string USER, this have to be an existing Useraccount with appropriate rights
*** (<span style='color:#FF0000'>m</span>) string PASSWORD, this has to match the password for the account.
*** (<span style='color:#FF0000'>m</span>) int surveyID, Id of the survey from which participants will be mailed
*** (<span style='color:#FF0000'>m</span>) string type, the kind of email you like to send (invite, remind or custom)
*** int $maxLsrcEmails, if you want to override $maxemails setting in config.php for sending mails with lsrc: here you go.
*** string subject, only needed if type==custom, the subject for the mail to be send.
*** string emailText, only needed if type==custom, the text for the mail to be send.
** '''Returns''':
*** "X Mails send" or "No Mails to send" in custom mode.
*** "X Mails send. X Mails left to send" or "No Mails to send" in invite mode.
*** "X Reminders send. X Reminders left to send" or "No Reminders to send" in remind mode.
** '''Possible Faults''':
*** throw new SoapFault("Authentication: ", "User or password wrong");
*** throw new SoapFault("Server: ", "Mandatory Parameters missing");
*** throw new SoapFault("Type: ", "Wrong send Type given. Possible types are: custom, invite or remind");
** '''Note''':
*** invite: When $maxemails is set the function sends only $maxemails in one go. If you call it again, it will go on to send the invitations, until everyone is invited.
*** remind: When $maxemails is set, it will only send $maxemails in one go. It checks if reminders have been send to other participants and if there are participants who received less reminders than others, the script will first send reminders to those who have not been reminded so often, until the remindercount is equal.
*** custom: $maxemails have no effect in custom mode. I have no solution for counting those who have been mailed before.

==sInsertToken==
* String '''sInsertToken'''(string USER, string PASSWORD, int SurveyID, string Token)
** '''Purpose''': Creates and populates a table {dbprefix}token_{SurveyID} and thus "closes" the survey. It is possible to add tokens to the existing table.
** '''Parameters''':
*** (<span style='color:#FF0000'>m</span>) int SurveyID, ID of the survey to close with a token table
*** string Token, a string with comma separated tokens. There is a possibility to set any other separator in config.php. Max. tested length of a string was 500,000 tokens, that makes a String of 5,500,000 Chars, this is just the limit of the apache webserver on my notebook (CoreDuo 1,6MHz, 1GB Ram) with default Resource Limits (60,60,16). I recommend to send max. 100,000 tokens over the webservice. Repeat for more tokens.
*** (<span style='color:#FF0000'>m</span>) string USER, this have to be an existing Admin-, Superadmin- or Useraccount with the rights to create and activate Surveys
*** (<span style='color:#FF0000'>m</span>) string PASSWORD, this has to match the password for the account.
** '''Returns''':
*** if everything went ok, it returns the String: "[X] Token given, [X] Token inserted"
** '''Possible Faults''':
*** throw new SoapFault("Authentication: ", "User or password wrong");
*** throw new SoapFault("Database: ", "Survey does not exists");
*** throw new SoapFault("Server: ", "Token could not be inserted");
** '''Note''':
*** Make sure on the client side that no token appears twice in the table. There is no check on this and won't be in the future. What happens if there are two same tokens? 2 participants will get the same token, one will fill out the form for both, and the other will get a message: "your token have already participated"
*** If there is no token table, it will create one and add the tokens.
*** If the Tokentable already exists, it just adds the given tokens to the existing table.

==sInsertParticipants==
* String '''sInsertParticipants'''(string USER, string PASSWORD, int SurveyID, string ParticipantData)
** '''Purpose''': Creates and populates a table {dbprefix}token_{SurveyID} and thus "closes" the survey. You can deliver some data to the token table. If you do not support a token, or an empty String as token, a unique token will be generated for the participant.
** '''Parameters''':
*** (<span style='color:#FF0000'>m</span>) int SurveyID, ID of the survey to close with a token table
*** string ParticipantData, The Data have to be in the right Syntax, it's like this:

<pre>

FIRSTNAME;LASTNAME;EMAIL;ATTRIB1;ATTRIB2;TOKEN::FIRSTNAME;LASTNAME;EMAIL;ATTRIB1;ATTRIB2;TOKEN

</pre>

'''NOTE: The Data Syntax change with 1.86'''. in order to take language, validfrom, validuntil and a variable count of attributes.

With 1.86 and later versions, it will have to be like this:

<pre>

FIRSTNAME;LASTNAME;EMAIL;LANGUAGE;TOKEN;VALIDFROM;VALIDUNTIL;attribute1,attribute2,attribute3::FIRSTNAME ... etc.

</pre>

note that the 8th field is the attributes field. There is no 9th field. You can seperate many attributes with a colon (,). The lsrc will create the needed fields in the db if they are not present. All Fields after LANGUAGE are optional and do not have to be send.

seperate the Datasets with double colons (::) and the fields with semicolon (;). The '''attrib1, attrib2 and token fields are optional''', you can just leave them out if not used. Note that the attrib field will get empty and not NULL, by now there where no complications, inform us, if you see some difficulties in not setting them NULL. Max. successfully tested length of a string was 3,000,000 Chars, this is just the limit of the apache webserver on my notebook (CoreDuo 1,6MHz, 1GB Ram) with default Resource Limits (60,60,16). I recommend to send max. 10,000 Datasets over the webservice at once(~1,000,000 chars). Repeat for more Datasets.
*** (<span style='color:#FF0000'>m</span>) string USER, this have to be an existing Admin-, Superadmin- or Useraccount with the rights to create and activate Surveys
*** (<span style='color:#FF0000'>m</span>) string PASSWORD, this has to match the password for the account.
** '''Returns''':
*** if everything went ok, it returns the String: "[X] Datasets given, [X] rows inserted. ";
** '''Possible Faults''':
*** throw new SoapFault("Authentication: ", "User or password wrong");
*** throw new SoapFault("Server: ", "No SurveyId given");
*** throw new SoapFault("Database: ", "Survey does not exists");
** '''Note''':
*** default tokenlength is 5 chars, if you want to change the length, goto lsrc.server.php, line 441
*** If the token table does not exists, it will be created, and if it does, the data will be added.

==sTokenReturn==
* string return '''sTokenReturn'''(string USER, string PASSWORD, int SurveyID)
** '''Purpose''': Gives back all Tokens, which did not complete the Survey, in a String seperated by commas.
** '''Parameters''':
*** (<span style='color:#FF0000'>m</span>) int SurveyID, the ID for the Survey from which you want get the unused tokens
*** (<span style='color:#FF0000'>m</span>) string USER, this have to be an existing Admin-, Superadmin- or Useraccount with the rights to create and activate Surveys
*** (<span style='color:#FF0000'>m</span>) string PASSWORD, this has to match the password for the account.
** '''Returns''':
*** Returns a String, a string of all unused tokens seperated by comma.
** '''Possible Faults''':
*** throw new SoapFault("Authentication: ", "User or password wrong");
*** throw new SoapFault("Database: ", "Survey does not exists");
*** throw new SoapFault("Server: ", "No SurveyId given");
*** throw new SoapFault("Database: ", "Token table for this Survey does not exists");
*** throw new SoapFault("Database: ", "No unused Tokens found");

==sGetFieldmap==
* string return '''sGetFieldmap'''(string USER, string PASSWORD, int SurveyID)
** '''Purpose''': Gives back the fieldmap for the survey

for example:

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

"fieldname","type","sid","gid","qid","aid","title","question","group_name","lid","lid1"

"111X779X39801","F","111","779","3980","1","1","How do you feel?","Paticipant feelings","",""

"111X779X39802","M","111","779","3980","2","1a","Why do you feel like this?","Paticipant feelings","",""

[...]

</syntaxhighlight>
** '''Parameters''':
*** (<span style='color:#FF0000'>m</span>) int SurveyID, the ID for the Survey from which you want to get the Fieldmap.
*** (<span style='color:#FF0000'>m</span>) string USER, this have to be an existing Admin-, Superadmin- or Useraccount with the rights to create and activate Surveys
*** (<span style='color:#FF0000'>m</span>) string PASSWORD, this has to match the password for the account.
** '''Returns''':
*** Returns a String, a string of the fieldmap, seperated by comma and blanks
** '''Possible Faults''':
*** throw new SoapFault("Authentication: ", "User or password wrong");
*** throw new SoapFault("Authentication: ", "You have no right to get fieldmaps from other peoples Surveys");
*** throw new SoapFault("Database: ", "Survey does not exists");
*** throw new SoapFault("Server: ", "No SurveyId given");

==fSendStatistic==

<span style='color:#FF0000'>''(since 1.86)''</span>
* '''fSendStatistic'''(string USER, string PASSWORD, int SurveyID, string Email, string doctype, string graph)
** '''Purpose''': sends an Statistic File as Attachment
** '''Parameters'''
*** user: Limesurvey user
*** password: Limesurvey Password
*** surveyId: ID of the survey from which statistics should be generated
*** email: the adress to which the statistic file is send
*** doctype: pdf, xls or html. With pdf or xls, the recipient gets an attached file with a short notice. With html, he gets an html e-mail without attachments
*** graph: turn graph generation on or off. Works only with pdf generation. Use '1' as a string if you want to enable it
** '''returns'''
*** string: 'XLS send'
*** string: 'PDF send'
*** string: 'HTML send'
** '''possible Faults'''
*** throw new SoapFault("Server: ", "Mandatory Parameters missing");
*** throw new SoapFault("Authentication: ", "User or password wrong");
*** throw new SoapFault("Authentication: ", "You have no right to send statistics from other peoples Surveys");
*** throw new SoapFault("Database: ", "Survey does not exists");
*** throw new SoapFault("Mail System", "Mail could not be send! Check your E-Mail Settings.");

=Testing=

For testing purposes, we made a testclient in php. Therefore you need a webserver to run it. If you test on one machine you need nothing to do, you can go to http://localhost/limesurvey/admin/lsrc/lsrc.testclient.php in your browser to test the webservices functionality.

Of Course this is very boring, because the apache talks with himself (and thats not the matter of a webservice).

The Testclient have two purposes:

1. It checks the Server(the one the testclient is running on!) for the PHP:SOAP Extension and installed libXML version and gives feedback if the enviroment does support SOAP via PHP:SOAP. This is very useful to check your Server and your Client towards PHP:SOAP compatibility. In addition to this, it will check if the wsdl file you want to connect to exists, it does not validate the wsdl file.

2. You can test the functions of the webservice.

If you test the webservice in realistic enviroment (two machines) you have to customize three things
* the lsrc.testclient.php needs to be on the machine where the webservice is NOT running, but it needs a webserver... download xampp from apachefriends if you dont have one <strike>(caution for Linux Users: you have to compile PHP5 with SOAP and enable the extension, futhermore you have to install libXML2. Last thing can by done very easy via Synaptics or apt-get)</strike> xampp for Linux works well with SOAP and libXML from version 1.7.
* this Line:

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

$limeUrl='https://localhost/limesource/limesurvey';

</syntaxhighlight>

At the beginning of lsrc.testclient.php needs to fit the target Limesurvey Installation Dir. localhost for servername is always wrong in this testcase, 127.0.0.1, too.

'''NOTES''':
* The Testclient is configured to use "admin" "password" as authentication. If you want to test with another user or password you have to change this vars in lsrc.client.php (between lines 20 and 30)
* If you just get a blank page on the testclient, make sure the path to the wsdl in the lsrc.client.php class is correct, and the var $enableLsrc is set to true in config.php or lsrc.config.php

=Notes=
* Security is enhanced: no action without permission (as good as Limesurveys Security itself --> very good)
* No headers or "Quick and Dirtys" anymore, no Scripts, just functions and a class.
* All configuration Variables are stored in lsrc.config.php by now
* There is a debug functionality, showing where the script runs through the code in an own log file. Use Apaches error.log in addition to find errors if you got any.
* LSRC is part of LimeSurvey, therefore it stands under GNU/GPL License v2 or later.
* SOAP Services and therefore LSRC only support UTF-8 charsets.
* LSRC works with AdoDB (MySql,Postgresql, MSSQL) .
* LSRC is tested, but under steady development, use on your own risk, test the functions before using them productively!

=Changes=

1.86
* new function fSendStatistics: to send statistics as attachment to an e-mail-address
* Datasyntax for sInsertParticipants changed in order to take validfrom, validuntil, language and a variable Set of attributes.

1.85
* Several improvements to stability.

1.82
* Added sVend Parameter to sCreateSurvey, to set the endtext
* sInsertParticipants takes a token in the dataset, however, if non is supported, it will be generated.
* a new variable $enableLsrc is introduced to enable the Lsrc only when it is used.
* a serious exploit has been fixed.

1.81
* Added sGetFieldmap function.
* The template.csv's changed.
* exported csv's prior 1.81 will not import over lsrc anymore. Import them via Browser and export them back to lsrc.

1.80 => 1.81
* Changed sImportGroup: imports '''all''' groups under $modDir, adds them to the survey. Not only the ones with mod_ as prefix. In addition, you can give Name and Description of the Group.
* New sImportQuestion: imports questions in $queDir and adds them to the last group
* New sImportFreetext: imports a Freetext question and changes the title and question to the Strings given. Previously, this function was called sImportQuestion.
* Changed sAvailableModules: type can be core, mod or que. "que" is new and gives back the names of all the questions available.
* New sSendEmail: send invitations, reminders and custom mails to participants of a survey over Limesurvey.

=ToDo / ToCome=
* <strike>sInsertParticipants should take a lang attribute for each participant</strike>

please add your feature requests to the [http://bugs.limesurvey.org bugtracker] if it is not listed here...

=Known Bugs (and workarounds)=
* With PHP 5.3.0, the testclient have problems to read the generated wsdl from lsrc.server.php?wsdl. You have to generate it an use the static file to test it.
* Surveys get not imported in 1.85, due to a bug. The bug is fixed and will be released with the next release. Talk to rakete if you need it earlier...
* exported csv's prior 1.81 will not import over lsrc anymore. Import them via Browser and export them back to lsrc to get them work again. (attributes moved from survey to survey_languagesettings)
* sInsertPaticipants and sInsertToken function: You should note, that in case of an Seperator at the beginning or the end of the Datastring, the return Message will recognize one more given Dataset or Token as inserted into the db...
* There is a bug with Webservices in general: Sometimes (~ 1 of 10.000 Cases) you will get an error message like "function 'anyFunction' does not exist on the server" or similar, altough everything is fine. Just wait a few Moments, clear you cache, phone your mom (she will be happy to hear from you ;)) and try again.
* Webservice will not work if the "install" dir is not renamed or deleted in limesurvey and $debug is not set to 2 -> "looks like we got no xml document" without errorlogs

please add your bug report to the [http://bugs.limesurvey.org bugtracker] if you found an Issue that is not listed here.

=Security=

There have been a security hole in the versions prior 1.82 (1.80RC2 to 1.81+). This leak could be used to compromise your webspace if it is weakly configured.

To minimise the risk of a security leak endanger your system, we disabled the lsrc by default with version 1.82 and you have to enable it explicity in your config.php.

Some things you can do to improve your security when using the lsrc:
* instead of setting the remotecontrol folder to 777, just create an empty file lsrc.wsdl with the rights 777
* disable the lsrc.log in lsrc.config.php
* Do not set the survey, groups, questions folders to 777 for saving lsrc templates directly within Limesurvey, instead, save the .csv on your local PC and upload them via ftp to the folders.
* delete lsrc.testclient.php, when in productive use. Lsrc.testclient.php could be used from unauthorized people to perform portscanning on other machines. The attacked webserver would be seeing your webserver as attacker, altough you did not perform any attack by yourself. This is not so serious, as this bahaviour of the testclient is not much valuable for any serious hacker.

RemoteControl

2009-11-19T08:44:39Z

Rakete:

__TOC__

=Introduction=

LimeSurvey RemoteControl is a PHP:SOAP based Web service application.

The LSRC makes it possible for developers to control specific functionality of Limesurvey from any other Application, without beeing restricted to PHP as a Programming language.

You can start a predefined survey (change titles and things), add predefined groups or questions to this coresurvey. Activate the survey, restrict it to start and endtime, make it closed, add Participant data or just tokens when you need them (your customer just bought a book and now you want to invite him to a closed survey automatically), return the unused tokens to the main application, delete a survey, get a fieldmap for a survey, invite or remind the participants of your survey, etc...

Be aware that this piece of code was originally written to bind LimeSurvey to a University management software in order to evaluate lectures. So there could be comments in the code or documentation, which have to do with my Company's Software or which are just a little bit confusing when you have nothing to do with University's or the German language.

Post any comments, wishes or bugs to the [http://bugs.limesurvey.org bugtracker].

==Files included in LSRC==
* lsrc.config.php (configuration variables)
* lsrc.server.php (the logical SOAP:Server brain. Programm logic is mainly in here )
* lsrc.helper.php (class LsrcHelper, this Class does the work. Mainly copied and customized from Limesurvey files. Especially for import tasks)
* lsrc_orig.wsdl (wsdl definition for SOAP messages. From this file the lsrc.wsdl is generated with correct paths)
* lsrc.testclient.php (to test the environment and functionality of the webservice on the fly)

== Directory included==
* \surveys (for the core survey .csv's.) Used by sCreateSurvey.
* \groups (for exported group .csv's . Used by sImportGroup. There should be always an empty group for importing, so you can add questions to a new group)
* \questions (for exported questions .csv's. sImportFreetext and sImportMatrix depend on "Freitext.csv" and "Matrix5.csv" which should be exported questions(Freetext and Array 5 point Matrix).

== Requirements==
* PHP >= 5.2.1 with PHP:SOAP Extension enabled
* libXML installed
* MySQL, PostgreSQL or (not recommended) MSSQL
* (optional) OpenSSL
* (optional) a Certificate for better Security

=Installation=

== How to install LSRC==

'''NOTE:''' It is included in Limesurvey since 1.80RC2, before 1.80RC4 it was called "japh" or "japhService"
* create a Dir "remotecontrol" in your LimeSurvey admin dir.
* copy the included files to the new directory.

== How to configure LSRC==
* first of all you have to '''enable the LSRC in LimeSurveys config.php''' or in lsrc.config.php
** set the variable '''$enableLsrc = true''';
* In the '''lsrc.config.php''' file, you can '''set all needed Variables''' for the LSRC in Section Variables.
** set the Error Handling. While configuring and testing it is very good to get all errors. If you are using lsrc in Production, you should comment error_reporting, so that it sticks to the servers defaults.
** $lsrcDebug, if set to true, the lsrc writes an own log. This log is helpful when implementing new features, if some function does not work, look where it hangs in this log. Should be set to false if in productive Use.
** $lsrcDebugLog, File where the log should be written to.
** ini_set("log_errors", "1"), Apaches log file (error.log) will get filed with php-errors. Very useful for debugging. Comment if in productive Mode.
** ini_set("soap.wsdl_cache_enabled", "0"), while testing, caching is not useful. If in productive Mode, turn this on or just comment the line to stick to server defaults.
** (optional) set $lsrcOverSSL to true, if you want SOAP to exchange the messages over SSL resp. https. It does not more or less than generating the target address in the wsdl with http: or https:.
** set the dirs, where the .csv files to import can be found. You will have to export some survey, you want to import and activate with LSRC, first.
** (optional) change $sLsrcSeparator = "your separator"; in lsrc.config.php if you wish to separate tokens for the sInsertToken function with any other separator than default, which is a comma.
** (optional) change $sDatasetSeperator= "your separator"; in lsrc.config.php if you wish to separate Datasets for the sInsertParticipants function with any other separator than default, which are two colons.
** (optional) change $sDatafieldSeperator= "your separator"; in lsrc.config.php if you wish to separate Datafields for the sInsertParticipants function with any other separator than default, which is a semicolon.
* the script needs rights to write files to the folder "admin/remotecontrol/" (lsrc.log, if logging is used and lsrc.wsdl). if(you cannot or don't want to set the directory rights to 777){create those two files(lsrc.log and lsrc.wsdl)in the lsrc dir with the permission to write them(777))
* If you want to save Survey, group or question csv's directly from Limesurvey into the lsrc Folders, you need to set them to 777, too. (Option can be enabled by adding $export4lsrc = true; to Limesurveys config.php)
* You may have to generate a wsdl file if you need a static one. Run lsrc.server.php?wsdl and the script will make a lsrc.wsdl with the correct server url included in the lsrc directory.
* If auto wsdl generation do not work properly (maybe virtual hosts make Problems, please report back, if so or not so, can't test at the moment) You have to set the url of the lsrc.server.php script in the last block of the wsdl

==How to enable OpenSSL / https Support==
* LSRC supports SSL over http resp. https.
* Your Webserver needs to support and enable OpenSSL (See your Webserver Manual)
* '''ATTENTION:''' Just set the Variable $lsrcOverSSL = true; in lsrc.config.php. After that, initialize your client like shown below, a wsdl file with correct URL will be generated automaticly for you:

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

new SoapClient('https://localhost/limesurvey/admin/lsrc.server.php?wsdl',

array('soap_version' => SOAP_1_1,

'trace' => 1));

</syntaxhighlight>
* 'ONLY FOLLOW THIS STEPS IF WSDL GENERATION DOES NOT WORK FOR YOU' <br>There are two locations in the code, where you force the webservice to use https

<nowiki>:</nowiki> 1. On the client side, when you call the SOAP-Server over wsdl. For 'https' do it like that:

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

new SoapClient('https://localhost/limesurvey/admin/remotecontrol/lsrc.wsdl', array('soap_version' => SOAP_1_1,

'trace' => 1));

</syntaxhighlight>

<nowiki>:</nowiki> for 'http' like that:

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

new SoapClient('http://localhost/limesurvey/admin/remotecontrol/lsrc.wsdl', array('soap_version' => SOAP_1_1,

'trace' => 1));

</syntaxhighlight>

<nowiki>:</nowiki> Note that the client will only get the wsdl-definition over https, to get the SOAP Messages over https, set the uri in the wsdl file, like below...

<nowiki>:</nowiki> 2. Here is the most important Step to SSL. At the End of the lsrc.wsdl file, last block, same procedure:

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

<port name='LsrcPort' binding='tns:LsrcBinding'>

<soap:address location='https://localhost/limesurvey/admin/remotecontrol/lsrc.server.php' />

</port>

</syntaxhighlight>

<nowiki>:</nowiki> or for normal http mode:

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

<port name='LsrcPort' binding='tns:LsrcBinding'>

<soap:address location='http://localhost/limesurvey/admin/remotecontrol/lsrc.server.php' />

</port>

</syntaxhighlight>

That's it! all request, response and fault messages will be transported over https...

=How to use LSRC=

==use the client==

There is a PHPclient (from version 1.86) in the remotecontrol folder. You can use this ClientClass to control Limesurvey from within your PHP Applications with ease.

Take a look at lsrc.testclient-new.php to get an impression of how it can be implemented.

Basically you just have to include the class, prepare the Client and start the function calls.

Example:

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

<?php

/**
* include the client class
*/

include_once("lsrc.client.php");

/**
* initiate the testclient object
*/

$testclient = new lsrcClient();

/**
* prepare the lsrcClient class (initiate the soapClient, set sid if needed)
*/

$testclient->prepare(333);

/**
* set user and password (only needed, when not set in the client class directly)
*/

$testclient->user = 'admin';

$testclient->pass = 'password';

/**
* set the path2wsdl (only needed, when not set in the client class directly)
*/

$testclient->path2wsdl = 'http://localhost/limesurvey/admin/remotecontrol/lsrc.server.php?wsdl'

/**
* call the function to create a survey
*/

$sReturn = $testclient->createSurvey("surveyName" , "surveyDescription", "welcomeText", "endText", "surveyAdmins@email.adress", "Survey Adminsname", "http://end.url", "Description of End Url", "template138");

echo $sReturn;

</syntaxhighlight>

This Skript initiates the client. The parameter at prepare, sets the surveyId. In this case it means we are going to create the survey with the Id 333. If you do not give an id, the survey will get a random id.

Next we set the user and password to use. You do not have to do this, as long as the inital values of the client are correct. But you may have to, if you build your app in a way, that different users use the client to create Surveys or edit them.

In the end, the survey is created with the createSurvey Method and the return is echoed.

==using the functions==

You will need a SOAP- or at least RPC-Client to communicate with the LSRC Webservice. How to create such a Client depends on the programming language you use.

The LSRC itself is written in PHP5 using the PHP:SOAP extension with SOAP 1.1.

In PHP you would initiate the Client-object and call a function from the Webservice with code like e.g.:

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

$wsdl="http://localhost/limesurvey/admin/remotecontrol/lsrc.server.php?wsdl";

$client = new SoapClient($wsdl, array('soap_version' => SOAP_1_1,

'trace' => 1));

try

{

$sReturn = $client->sInsertToken($user, $pass, $iVid, $sToken);

}

catch (SoapFault $fault)

{

$sOutput .= " <br/><br/>SOAP Error: ".$fault->faultcode." : ".$fault->faultstring;

}

</syntaxhighlight>

The LSRC offers some functions:

(<span style='color:#FF0000'>m</span>) means: Mandatory Parameter

==sCreateSurvey==

<span style='color:#FF0000'>Parameters changed after 1.81+! (sVend added)</span>
* String sCreateSurvey($sUser, $sPass, $iVid, $sVtit , $sVbes, $sVwel, $sVend, $sMail, $sName, $sUrl, $sUbes, $sVtyp )
** '''Purpose''': Creates a new survey. It imports an exported survey from any LS v1.xx. and changes some fields (in the current Version it changes SurveyTitle, SurveyDescription and SurveyWelcomeText, adminemail, adminname, url and url_description to the string which was given by the client.)
** '''Parameters''':
*** (<span style='color:#FF0000'>m</span>) string USER, this have to be an existing Useraccount with appropriate rights
*** (<span style='color:#FF0000'>m</span>) string PASSWORD, this has to match the password for the account.
*** (<span style='color:#FF0000'>m</span>) int $iVid, SurveyID desired ID for the Survey, make sure it doesn't already exist in LimeSurvey
*** (<span style='color:#FF0000'>m</span>) string $sVtit, SurveyTitle, should be the (Nr +)Name of the Event to be evaluated
*** (<span style='color:#FF0000'>m</span>) string $sVbes, Survey Description, This should be String put together with veransttyp + doztitle + dozname
*** string $sVwel, Survey Welcometext, A text shown before the survey starts. If not given it says: "Herzlich Willkommen zur Evaluation von "$sVtit"
*** string $sVend, Survey Endtext, Text shown at the endpage.
*** string $sMail, Admin Email, Email Adress of the responsible person for this survey
*** string $sName, Name of the responsible person for this survey
*** string $sUrl, Url of the Link, shown on the last page of survey.
*** string $sUbes, Description String of the URL above. ( <a href='$sUrl'>$sUbes</a> )
*** string $sVtyp, The type of Event that should be evaluated. Use in combination with sAvailableModules with $mode='core' to get all available "types"
** '''Returns''':
*** if everything went fine, it returns the SurveyID from the created survey
** '''Possible Faults''':
*** throw new SoapFault("Authentication: ", "User or password wrong");
*** throw new SoapFault("Database: ", "SurveyID already exists");
*** throw new SoapFault("Server: ", "Mandatory Parameters missing");
*** throw new SoapFault("Server: ", "Import went wrong somehow");
** '''Note''':
*** Goto line 714 in lsrc.helper.php to see what can be done and customized while importing.
*** If you want Limesurvey to give your Survey a random Number if the given ID exist (because you do not need a specific identification for your surveys), just go into the function sCreateSurvey in lsrc.server.php and delete or comment out the if($lsrcHelper->surveyExists($iVid)) clause. In Result, Limesurvey will give your survey a random ID when the given ID exists.

==sActivateSurvey==
* String '''sActivateSurvey'''(string USER, string PASSWORD, int SurveyID, date start, date end)
** '''Purpose''': Activates an existing survey and set start and enddate optional
** '''Parameters''':
*** (<span style='color:#FF0000'>m</span>) string USER, this have to be an existing Useraccount with appropriate rights
*** (<span style='color:#FF0000'>m</span>) string PASSWORD, this has to match the password for the account.
*** (<span style='color:#FF0000'>m</span>) int SurveyID, the SurveyID for the Survey to activate.
*** date start, date for the Survey to start. 2008-10-22 means it starts exactly at 2008-10-22 00:00:00 Servertime
*** date end, date for the Survey to end. 2008-10-22 means it ends exactly at 2008-10-22 23:59:59 Servertime. Nobody can access nor complete the Survey only a second later.
** '''Returns''':
*** if everything went fine, it returns the SurveyID from the activated survey
** '''Possible Faults''':
*** throw new SoapFault("Authentication: ", "User or password wrong");
*** throw new SoapFault("Database: ", "Survey you want to activate does not exists");
*** throw new SoapFault("Server: ", "Mandatory Parameters missing");
*** throw new SoapFault("Server: ", "Activation went wrong somehow");
** '''Note''':
*** You can set startDate and/or endDate after activation if needed. Just run the function again with desired parameters.

==sImportGroup==
* String '''sImportGroup'''(string USER, string PASSWORD, int SurveyID, String Module, String groupName, String groupDescription)
** '''Purpose''': Imports an exported group file (.csv) to the Survey given by SurveyID
** '''Parameters''':
*** (<span style='color:#FF0000'>m</span>) string USER, this have to be an existing Useraccount with appropriate rights
*** (<span style='color:#FF0000'>m</span>) string PASSWORD, this has to match the password for the account.
*** (<span style='color:#FF0000'>m</span>) int SurveyID, the SurveyID
*** (<span style='color:#FF0000'>m</span>) string Module, the filename of the Group you want to add to the Survey. Use sAvailableModules to get the available groups.
*** string groupName, the Title the Group gets. If not set, it will use the title given in the .csv.
*** string groupDescription, Description of the group. If not set, it will use the description given in the .csv.
** '''Returns''':
*** if everything went fine, it returns the String "Import OK"
** '''Possible Faults''':
*** throw new SoapFault("Authentication: ", "User or password wrong");
*** throw new SoapFault("Authentication: ", "You have no right to change Surveys from other people");
*** throw new SoapFault("Server: ", "Survey Module $sMod does not exist");
*** throw new SoapFault("Server: ", "Group does not support Surveys Baselanguage ($langcode)");
** '''Note''':
*** It imports only exported groups as .csv which lay under \groups or any other dir given in lsrc.config.php
*** <strike>It imports only the files beginning with "mod_" ending with ".csv"</strike>
*** The Param Module must only contain the "name of the Module": Only the String before ".csv"
*** The baselanguage of the group to import, have to match the baselanguage of the coresurvey.

==sImportQuestion==
* String '''sImportQuestion'''(string USER, string PASSWORD, int SurveyID, String Module, String mandatory)
** '''Purpose''': Imports an exported question file (.csv) to the last group of the Survey given by SurveyID. This is meant for predefined questions stored in the /question directory
** '''Parameters''':
*** (<span style='color:#FF0000'>m</span>) string USER, this have to be an existing Useraccount with appropriate rights
*** (<span style='color:#FF0000'>m</span>) string PASSWORD, this has to match the password for the account.
*** (<span style='color:#FF0000'>m</span>) int SurveyID, the SurveyID
*** (<span style='color:#FF0000'>m</span>) String Module, the name of the csv file you want to add to the Survey, without extension(.csv).
*** String mandatory, default='N' set to 'Y' if you want that question mandatory
** '''Returns''':
*** if everything went fine, it returns the String "OK"
** '''Possible Faults''':
*** throw new SoapFault("Authentication: ", "User or password wrong");
*** throw new SoapFault("Authentication: ", "You have no right to change Surveys from other people");
*** throw new SoapFault("Server: ", "Group does not support Surveys Baselanguage ($langcode)");
** '''Note''':
*** It imports only exported questions as .csv which lay under \questions or any dir given in lsrc.config.php
*** The baselanguage of the question to import, have to match the baselanguage of the core survey.

==sImportFreetext==
* String '''sImportFreetext'''(string USER, string PASSWORD, int SurveyID, String questionTitle, String questionText, String questionhelp, String module='freitext', string mandatory)
** '''Purpose''': Imports an exported question file (.csv) to the last Group of the survey given by SurveyID and changes the Title, question and helptext. This is meant for importing empty question.csv's (Text Questions)
** '''Parameters''':
*** (<span style='color:#FF0000'>m</span>) string USER, this have to be an existing Useraccount with appropriate rights
*** (<span style='color:#FF0000'>m</span>) string PASSWORD, this has to match the password for the account.
*** (<span style='color:#FF0000'>m</span>) int SurveyID, the SurveyID
*** String questionTitle, Name or Categorie of the Question
*** String questionText, The Question itself
*** String questionhelp, A little Help text for better understanding of the Question
*** String module, the name of the Module you want to add to the Survey. It should be "Freitext" by default.
*** String mandatory, make the question mandatory by giving 'Y' as this param.
** '''Returns''':
*** if everything went fine, it returns the String "OK"
** '''Possible Faults''':
*** throw new SoapFault("Authentication: ", "User or password wrong");
*** throw new SoapFault("Authentication: ", "You have no right to change Surveys from other people");
*** throw new SoapFault("Server: ", "Group does not support Surveys Baselanguage ($langcode)");
** '''Note''':
*** It imports only exported questions as .csv which lay under \questions or any dir given in lsrc.config.php
*** It is meant for importing one shortext, Longtext or Hugetext Question and changing the Question and Helptext.
*** The baselanguage of the question to import, have to match the baselanguage of the core survey.
*** Be sure to have at least one proper .csv (Freitext.csv) in the proper directory (questions), to use this function.
*** Use sAvailableModules with mode='que' to get all question .csv's available.

==sImportMatrix==
* String '''sImportMatrix'''(string USER, string PASSWORD, int SurveyID, String Module, String questionText, String questionhelp, String questionItems)
** '''Purpose''': Imports an exported question file (Matrix5.csv) to the Survey given by SurveyID and changes the question, helptext and gives Items to the 5 Scale Matrix. This is meant for importing one 5 Scale Matrix Question.
** '''Parameters''':
*** (<span style='color:#FF0000'>m</span>) string USER, this have to be an existing Useraccount with appropriate rights
*** (<span style='color:#FF0000'>m</span>) string PASSWORD, this has to match the password for the account.
*** (<span style='color:#FF0000'>m</span>) int SurveyID, the SurveyID
*** string Module, the name of the Module you want to add to the Survey. It should be "Matrix" by default.
*** String questionText, the question or text to the Matrix
*** String questionhelp, the help text
*** String questionItems, the Items that should be rated, separated by commas
** '''Returns''':
*** if everything went fine, it returns the String "OK"
** '''Possible Faults''':
*** throw new SoapFault("Authentication: ", "User or password wrong");
*** throw new SoapFault("Server: ", "Group does not support Surveys Baselanguage ($langcode)");
** '''Note''':
*** It imports only exported groups as .csv which lay under docs\demosurveys\studiply_mod
*** It is meant for importing a group with only one 5 Scale Matrix Question and changing the Question and Helptext and add Items.
*** Be sure to use an user with the surveys baselanguage as default, because this language is used to fill the language fields for answers and questions while importing.

==sAvailableModules==
* String '''sAvailableModules'''(string USER, string PASSWORD, string mode)
** '''Purpose''': Returning all the csv Names of the csv's in the Directorys configured in lsrc.config.php
** '''Parameters''':
*** (<span style='color:#FF0000'>m</span>) string USER, this have to be an existing Useraccount with appropriate rights
*** (<span style='color:#FF0000'>m</span>) string PASSWORD, this has to match the password for the account.
*** String mode, (optional) "mod" for the available groups, "core" for the coreSurveys, "que" for addable questions. Default, when not given is "mod".
** '''Returns''':
*** if everything went fine, it returns a String with all surveys, groups or questions (depends on mode) in the Dir given in lsrc.config.php, separated by comma.
** '''Possible Faults''':
*** throw new SoapFault("Authentication: ", "User or password wrong");
** '''Note''':

==sSendEmail==
* String sSendEmail($sUser, $sPass, $surveyID, $type, $maxLsrcEmails='', $subject='', $emailText='')
** '''Purpose''': sends Emails to Participants of a particular survey
** '''Parameters''':
*** (<span style='color:#FF0000'>m</span>) string USER, this have to be an existing Useraccount with appropriate rights
*** (<span style='color:#FF0000'>m</span>) string PASSWORD, this has to match the password for the account.
*** (<span style='color:#FF0000'>m</span>) int surveyID, Id of the survey from which participants will be mailed
*** (<span style='color:#FF0000'>m</span>) string type, the kind of email you like to send (invite, remind or custom)
*** int $maxLsrcEmails, if you want to override $maxemails setting in config.php for sending mails with lsrc: here you go.
*** string subject, only needed if type==custom, the subject for the mail to be send.
*** string emailText, only needed if type==custom, the text for the mail to be send.
** '''Returns''':
*** "X Mails send" or "No Mails to send" in custom mode.
*** "X Mails send. X Mails left to send" or "No Mails to send" in invite mode.
*** "X Reminders send. X Reminders left to send" or "No Reminders to send" in remind mode.
** '''Possible Faults''':
*** throw new SoapFault("Authentication: ", "User or password wrong");
*** throw new SoapFault("Server: ", "Mandatory Parameters missing");
*** throw new SoapFault("Type: ", "Wrong send Type given. Possible types are: custom, invite or remind");
** '''Note''':
*** invite: When $maxemails is set the function sends only $maxemails in one go. If you call it again, it will go on to send the invitations, until everyone is invited.
*** remind: When $maxemails is set, it will only send $maxemails in one go. It checks if reminders have been send to other participants and if there are participants who received less reminders than others, the script will first send reminders to those who have not been reminded so often, until the remindercount is equal.
*** custom: $maxemails have no effect in custom mode. I have no solution for counting those who have been mailed before.

==sInsertToken==
* String '''sInsertToken'''(string USER, string PASSWORD, int SurveyID, string Token)
** '''Purpose''': Creates and populates a table {dbprefix}token_{SurveyID} and thus "closes" the survey. It is possible to add tokens to the existing table.
** '''Parameters''':
*** (<span style='color:#FF0000'>m</span>) int SurveyID, ID of the survey to close with a token table
*** string Token, a string with comma separated tokens. There is a possibility to set any other separator in config.php. Max. tested length of a string was 500,000 tokens, that makes a String of 5,500,000 Chars, this is just the limit of the apache webserver on my notebook (CoreDuo 1,6MHz, 1GB Ram) with default Resource Limits (60,60,16). I recommend to send max. 100,000 tokens over the webservice. Repeat for more tokens.
*** (<span style='color:#FF0000'>m</span>) string USER, this have to be an existing Admin-, Superadmin- or Useraccount with the rights to create and activate Surveys
*** (<span style='color:#FF0000'>m</span>) string PASSWORD, this has to match the password for the account.
** '''Returns''':
*** if everything went ok, it returns the String: "[X] Token given, [X] Token inserted"
** '''Possible Faults''':
*** throw new SoapFault("Authentication: ", "User or password wrong");
*** throw new SoapFault("Database: ", "Survey does not exists");
*** throw new SoapFault("Server: ", "Token could not be inserted");
** '''Note''':
*** Make sure on the client side that no token appears twice in the table. There is no check on this and won't be in the future. What happens if there are two same tokens? 2 participants will get the same token, one will fill out the form for both, and the other will get a message: "your token have already participated"
*** If there is no token table, it will create one and add the tokens.
*** If the Tokentable already exists, it just adds the given tokens to the existing table.

==sInsertParticipants==
* String '''sInsertParticipants'''(string USER, string PASSWORD, int SurveyID, string ParticipantData)
** '''Purpose''': Creates and populates a table {dbprefix}token_{SurveyID} and thus "closes" the survey. You can deliver some data to the token table. If you do not support a token, or an empty String as token, a unique token will be generated for the participant.
** '''Parameters''':
*** (<span style='color:#FF0000'>m</span>) int SurveyID, ID of the survey to close with a token table
*** string ParticipantData, The Data have to be in the right Syntax, it's like this:

<pre>

FIRSTNAME;LASTNAME;EMAIL;ATTRIB1;ATTRIB2;TOKEN::FIRSTNAME;LASTNAME;EMAIL;ATTRIB1;ATTRIB2;TOKEN

</pre>

'''NOTE: The Data Syntax change with 1.86'''. in order to take language, validfrom, validuntil and a variable count of attributes.

With 1.86 and later versions, it will have to be like this:

<pre>

FIRSTNAME;LASTNAME;EMAIL;LANGUAGE;TOKEN;VALIDFROM;VALIDUNTIL;attribute1,attribute2,attribute3::FIRSTNAME ... etc.

</pre>

note that the 8th field is the attributes field. There is no 9th field. You can seperate many attributes with a colon (,). The lsrc will create the needed fields in the db if they are not present. All Fields after LANGUAGE are optional and do not have to be send.

seperate the Datasets with double colons (::) and the fields with semicolon (;). The '''attrib1, attrib2 and token fields are optional''', you can just leave them out if not used. Note that the attrib field will get empty and not NULL, by now there where no complications, inform us, if you see some difficulties in not setting them NULL. Max. successfully tested length of a string was 3,000,000 Chars, this is just the limit of the apache webserver on my notebook (CoreDuo 1,6MHz, 1GB Ram) with default Resource Limits (60,60,16). I recommend to send max. 10,000 Datasets over the webservice at once(~1,000,000 chars). Repeat for more Datasets.
*** (<span style='color:#FF0000'>m</span>) string USER, this have to be an existing Admin-, Superadmin- or Useraccount with the rights to create and activate Surveys
*** (<span style='color:#FF0000'>m</span>) string PASSWORD, this has to match the password for the account.
** '''Returns''':
*** if everything went ok, it returns the String: "[X] Datasets given, [X] rows inserted. ";
** '''Possible Faults''':
*** throw new SoapFault("Authentication: ", "User or password wrong");
*** throw new SoapFault("Server: ", "No SurveyId given");
*** throw new SoapFault("Database: ", "Survey does not exists");
** '''Note''':
*** default tokenlength is 5 chars, if you want to change the length, goto lsrc.server.php, line 441
*** If the token table does not exists, it will be created, and if it does, the data will be added.

==sTokenReturn==
* string return '''sTokenReturn'''(string USER, string PASSWORD, int SurveyID)
** '''Purpose''': Gives back all Tokens, which did not complete the Survey, in a String seperated by commas.
** '''Parameters''':
*** (<span style='color:#FF0000'>m</span>) int SurveyID, the ID for the Survey from which you want get the unused tokens
*** (<span style='color:#FF0000'>m</span>) string USER, this have to be an existing Admin-, Superadmin- or Useraccount with the rights to create and activate Surveys
*** (<span style='color:#FF0000'>m</span>) string PASSWORD, this has to match the password for the account.
** '''Returns''':
*** Returns a String, a string of all unused tokens seperated by comma.
** '''Possible Faults''':
*** throw new SoapFault("Authentication: ", "User or password wrong");
*** throw new SoapFault("Database: ", "Survey does not exists");
*** throw new SoapFault("Server: ", "No SurveyId given");
*** throw new SoapFault("Database: ", "Token table for this Survey does not exists");
*** throw new SoapFault("Database: ", "No unused Tokens found");

==sGetFieldmap==
* string return '''sGetFieldmap'''(string USER, string PASSWORD, int SurveyID)
** '''Purpose''': Gives back the fieldmap for the survey

for example:

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

"fieldname","type","sid","gid","qid","aid","title","question","group_name","lid","lid1"

"111X779X39801","F","111","779","3980","1","1","How do you feel?","Paticipant feelings","",""

"111X779X39802","M","111","779","3980","2","1a","Why do you feel like this?","Paticipant feelings","",""

[...]

</syntaxhighlight>
** '''Parameters''':
*** (<span style='color:#FF0000'>m</span>) int SurveyID, the ID for the Survey from which you want to get the Fieldmap.
*** (<span style='color:#FF0000'>m</span>) string USER, this have to be an existing Admin-, Superadmin- or Useraccount with the rights to create and activate Surveys
*** (<span style='color:#FF0000'>m</span>) string PASSWORD, this has to match the password for the account.
** '''Returns''':
*** Returns a String, a string of the fieldmap, seperated by comma and blanks
** '''Possible Faults''':
*** throw new SoapFault("Authentication: ", "User or password wrong");
*** throw new SoapFault("Authentication: ", "You have no right to get fieldmaps from other peoples Surveys");
*** throw new SoapFault("Database: ", "Survey does not exists");
*** throw new SoapFault("Server: ", "No SurveyId given");

==fSendStatistic==

<span style='color:#FF0000'>''(since 1.86)''</span>
* '''fSendStatistic'''(string USER, string PASSWORD, int SurveyID, string Email, string doctype, string graph)
** '''Purpose''': sends an Statistic File as Attachment
** '''Parameters'''
*** user: Limesurvey user
*** password: Limesurvey Password
*** surveyId: ID of the survey from which statistics should be generated
*** email: the adress to which the statistic file is send
*** doctype: pdf, xls or html. With pdf or xls, the recipient gets an attached file with a short notice. With html, he gets an html e-mail without attachments
*** graph: turn graph generation on or off. Works only with pdf generation. Use '1' as a string if you want to enable it
** '''returns'''
*** string: 'XLS send'
*** string: 'PDF send'
*** string: 'HTML send'
** '''possible Faults'''
*** throw new SoapFault("Server: ", "Mandatory Parameters missing");
*** throw new SoapFault("Authentication: ", "User or password wrong");
*** throw new SoapFault("Authentication: ", "You have no right to send statistics from other peoples Surveys");
*** throw new SoapFault("Database: ", "Survey does not exists");
*** throw new SoapFault("Mail System", "Mail could not be send! Check your E-Mail Settings.");

=Testing=

For testing purposes, we made a testclient in php. Therefore you need a webserver to run it. If you test on one machine you need nothing to do, you can go to http://localhost/limesurvey/admin/lsrc/lsrc.testclient.php in your browser to test the webservices functionality.

Of Course this is very boring, because the apache talks with himself (and thats not the matter of a webservice).

The Testclient have two purposes:

1. It checks the Server(the one the testclient is running on!) for the PHP:SOAP Extension and installed libXML version and gives feedback if the enviroment does support SOAP via PHP:SOAP. This is very useful to check your Server and your Client towards PHP:SOAP compatibility. In addition to this, it will check if the wsdl file you want to connect to exists, it does not validate the wsdl file.

2. You can test the functions of the webservice.

If you test the webservice in realistic enviroment (two machines) you have to customize three things
* the lsrc.testclient.php needs to be on the machine where the webservice is NOT running, but it needs a webserver... download xampp from apachefriends if you dont have one <strike>(caution for Linux Users: you have to compile PHP5 with SOAP and enable the extension, futhermore you have to install libXML2. Last thing can by done very easy via Synaptics or apt-get)</strike> xampp for Linux works well with SOAP and libXML from version 1.7.
* this Line:

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

$limeUrl='https://localhost/limesource/limesurvey';

</syntaxhighlight>

At the beginning of lsrc.testclient.php needs to fit the target Limesurvey Installation Dir. localhost for servername is always wrong in this testcase, 127.0.0.1, too.

'''NOTES''':
* The Testclient is configured to use "admin" "password" as authentication. If you want to test with another user or password you have to change this vars in lsrc.client.php (between lines 20 and 30)
* If you just get a blank page on the testclient, make sure the path to the wsdl in the lsrc.client.php class is correct, and the var $enableLsrc is set to true in config.php or lsrc.config.php

=Notes=
* Security is enhanced: no action without permission (as good as Limesurveys Security itself --> very good)
* No headers or "Quick and Dirtys" anymore, no Scripts, just functions and a class.
* All configuration Variables are stored in lsrc.config.php by now
* There is a debug functionality, showing where the script runs through the code in an own log file. Use Apaches error.log in addition to find errors if you got any.
* LSRC is part of LimeSurvey, therefore it stands under GNU/GPL License v2 or later.
* SOAP Services and therefore LSRC only support UTF-8 charsets.
* LSRC works with AdoDB (MySql,Postgresql, MSSQL) .
* LSRC is tested, but under steady development, use on your own risk, test the functions before using them productively!

=Changes=

1.86
* new function fSendStatistics: to send statistics as attachment to an e-mail-address
* Datasyntax for sInsertParticipants changed in order to take validfrom, validuntil, language and a variable Set of attributes.

1.85
* Several improvements to stability.

1.82
* Added sVend Parameter to sCreateSurvey, to set the endtext
* sInsertParticipants takes a token in the dataset, however, if non is supported, it will be generated.
* a new variable $enableLsrc is introduced to enable the Lsrc only when it is used.
* a serious exploit has been fixed.

1.81
* Added sGetFieldmap function.
* The template.csv's changed.
* exported csv's prior 1.81 will not import over lsrc anymore. Import them via Browser and export them back to lsrc.

1.80 => 1.81
* Changed sImportGroup: imports '''all''' groups under $modDir, adds them to the survey. Not only the ones with mod_ as prefix. In addition, you can give Name and Description of the Group.
* New sImportQuestion: imports questions in $queDir and adds them to the last group
* New sImportFreetext: imports a Freetext question and changes the title and question to the Strings given. Previously, this function was called sImportQuestion.
* Changed sAvailableModules: type can be core, mod or que. "que" is new and gives back the names of all the questions available.
* New sSendEmail: send invitations, reminders and custom mails to participants of a survey over Limesurvey.

=ToDo / ToCome=
* <strike>sInsertParticipants should take a lang attribute for each participant</strike>

please add your feature requests to the [http://bugs.limesurvey.org bugtracker] if it is not listed here...

=Known Bugs (and workarounds)=
* With PHP 5.3.0, the testclient have problems to read the generated wsdl from lsrc.server.php?wsdl. You have to generate it an use the static file to test it.
* Surveys get not imported in 1.85, due to a bug. The bug is fixed and will be released with the next release. Talk to rakete if you need it earlier...
* exported csv's prior 1.81 will not import over lsrc anymore. Import them via Browser and export them back to lsrc to get them work again. (attributes moved from survey to survey_languagesettings)
* sInsertPaticipants and sInsertToken function: You should note, that in case of an Seperator at the beginning or the end of the Datastring, the return Message will recognize one more given Dataset or Token as inserted into the db...
* There is a bug with Webservices in general: Sometimes (~ 1 of 10.000 Cases) you will get an error message like "function 'anyFunction' does not exist on the server" or similar, altough everything is fine. Just wait a few Moments, clear you cache, phone your mom (she will be happy to hear from you ;)) and try again.
* Webservice will not work if the "install" dir is not renamed or deleted in limesurvey and $debug is not set to 2 -> "looks like we got no xml document" without errorlogs

please add your bug report to the [http://bugs.limesurvey.org bugtracker] if you found an Issue that is not listed here.

=Security=

There have been a security hole in the versions prior 1.82 (1.80RC2 to 1.81+). This leak could be used to compromise your webspace if it is weakly configured.

To minimise the risk of a security leak endanger your system, we disabled the lsrc by default with version 1.82 and you have to enable it explicity in your config.php.

Some things you can do to improve your security when using the lsrc:
* instead of setting the remotecontrol folder to 777, just create an empty file lsrc.wsdl with the rights 777
* disable the lsrc.log in lsrc.config.php
* Do not set the survey, groups, questions folders to 777 for saving lsrc templates directly within Limesurvey, instead, save the .csv on your local PC and upload them via ftp to the folders.
* delete lsrc.testclient.php, when in productive use. Lsrc.testclient.php could be used from unauthorized people to perform portscanning on other machines. The attacked webserver would be seeing your webserver as attacker, altough you did not perform any attack by yourself. This is not so serious, as this bahaviour of the testclient is not much valuable for any serious hacker.

Workarounds

2009-11-16T16:54:59Z

Rakete:

<div class="simplebox"><center>'''Please keep in mind that the workarounds published here are no official Limesurvey extensions but solutions that other users created for themselves.<br/><span style='color:#EE0000,#FFFFFF'>Therefore we can't give support for any solution on this page.</span><br/>Please contact the users that, thankfully, shared their solutions with the community if you have any questions.'''</center></div>

''If you have successfully tested a workaround please update the "tested with:..." entry. Thanks!''

Contents:__TOC__

=Question Design, Layout, Templating=

==Getting rid of the question mark symbol (help.gif)==

''Tested with: 1.80+ (6536)''

To get rid of the question mark symbol that LimeSurvey displays at the end of a question, you can either upload an empty help.gif into the template folder (as discussed in the forum) - or - you can use the Template editor: Open the ''template.css'' of your template and search for ''div.questionhelp img'', then add a ''visibility:hidden;''

It will look something like this:

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

div.questionhelp img

{

margin:5px;

visibility:hidden;

}

</syntaxhighlight>

==Use komma/virgule (komma: German data format) (virgule: french format) instead of dot when entering numbers==

''Tested with: LS1.53, LS1.70''

To use kommas instead of dots when entering numbers make the following changes:

Search the "qanda.php" for the function "function do_numerical" which should look like this <syntaxhighlight lang="php" enclose="div">inhibited_keypress=\"return goodchars(event,'0123456789.')\"</syntaxhighlight>

and replace the dot with a comma.

==Require users to check a box agreeing to privacy statement before registering for a survey==

If you need to have users positively acknowledge a privacy statement before submitting a registration form, the following will help you do this.

It involves a minor modification to common.php in versions up to 1.85. Later versions may not require this.

Edit common.php and look for the line (at approximately line 3014)

<syntaxhighlight lang="php" enclose="div">$registerform .= "<tr><td></td><td>

<input class='submit' type='submit' value='".$clang->gT("Continue")."' />"

</syntaxhighlight>

and change it to:

<syntaxhighlight lang="php" enclose="div">$registerform .= "<tr><td></td><td>

<input id='registercontinue' class='submit' type='submit' value='".$clang->gT("Continue")."' />"

</syntaxhighlight>

Then save common.php. This gives you DOM access to the "continue" button on the register form, but will have no other practical effect or change to LimeSurvey's operations.

Next, you need to edit the template you are using (see the documentation on the Template editor if you don't know how to do this).

In the template editor, open the screen "Register page" and select the file "register.pstpl"

There are two modifications you need to make to this file. The first is to add the following code after the line that says ''{REGISTERFORM}''.

<syntaxhighlight lang="php" enclose="div"><script type='text/javascript'>

</script></syntaxhighlight>

This code disables the "Continue" button so that nobody can process the registration form until they've clicked the checkbox.

The second modification to make is to be done between the lines {REGISTERMESSAGE2} and {REGISTERFORM}. Add:

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

<label> Accept

<input type='radio'

name="privacy"

value="YES"

onChange="if(this.checked) {

document.getElementById('registercontinue').disabled=false;

}" />

</label>

<label>I don't accept

<input type='radio'

name="privacy"

value="NO"

CHECKED

onChange="if(this.checked) {

document.getElementById('registercontinue').disabled=true;

}" />

</label>

</center></syntaxhighlight>

Then the users will have to agree to whatever text you replace "Do you agree to privacy stuff?" before they continue on and register.

(Thanks to ''Pippo_Jedi'' for helping work this out)

==Different progress indicator==

''Tested with: ''

User [http://www.limesurvey.org/component/option,com_comprofiler/task,userProfile/Itemid,76/user,5344/lang,en/ Ypse] implemented a new kind of progress indicator. Instead of showing the progress in percent his solution marks the progress like this:

''3/6 (3 step of 6) Progress 14 %''

The code and a short tutorial on how to integrate this solution can be found in the [http://bugs.limesurvey.org/view.php?id=1893 bug and feature tracker].

==Delete unwanted gaps in question title==

''Tested with: ''

When copying data (questions, answers, ...) from MS Word or other applications into the editor there might occur some gaps in the question title.

There are two solutions to this:
# Use popup mode and manually delete unwanting extra html tags (requires html knowledge).
# Disable paste word feature: Tweak your limesurvey-config.js file in limesurvey/admin/scripts/fckeditor.26 and set the following option to true:

<syntaxhighlight lang="php" enclose="div">FCKConfig.ForcePasteAsPlainText = true ;</syntaxhighlight>

After that clear you browser cache and try again.

==Removing the * (asterisk) from mandatory questions==

''Tested with: ''

Mandatory questions are always preceded with a * to indicate that they are mandatory. You can modify the colour of this, or hide it completely by editing the css style in the template you are using.

The default template uses the following, in the "startpage.pstpl" file:

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

{

color: #FF0000;

font-size: 9pt;

font-family: verdana;

}</syntaxhighlight>

To hide the asterisk completely, add a line

<syntaxhighlight lang="php" enclose="div">display: none;</syntaxhighlight>

To change the colour, change the colour code.

Some templates don't have a style defined for .asterisk, and in this case you'll need to add one in the style sheet.

==How to change the <font-size> tags using CSS==

''This workaround was deleted because it is outdated. Such changes can be done by [http://docs.limesurvey.org/tiki-index.php?page=Template+editor&structure;=English+Instructions+for+LimeSurvey#Styling_questions_with_CSS adjusting template.css] of your template.

==Question type variation: Scale with bars (one and two sided)==

''Tested with: ''

Some methodogical issues to think about: Very often a common scale as 1 to 5 or -2 to +2 fits all needs, as the shown subject is clearly defined as positive or negative. As soon as you would reduce the influence from the question and scale on the respondent, you will need something neutral to determine tendences, emphases and so on.

So I put up a new variation of the one and two sided array question:

ttp://www.limesurvey.org/images/fbfiles/images/example_bar_scale.jpg

In my example the left side reads "strategical planning" and the right side "operative business". None of these are purely negative or positive, so the bars only show in which direction the balancing point moves.

To realize a question as shown above just do as follows:

Set up as many bars as you will need (in my example there are four different bars in total) with a graphic program like PAINT .NET, GIMP or similar ones (yes, you may also use commercial software like Photoshop). To prevent the bars from looking twitchy, designate the size in advance. I did one bar 60x15 px, one 45x15px, one 30x15px and at last 15x15px. Save them as PNG, JPG or GIF.
# Create a new label set within Lime. Call it whatever you like.
# Enter a code number at first, then press the pencil symbol to enter the editor.
#Press the "Insert / edit image" button and upload the bar you want to insert with the FCK upload tool. Then choose the uploaded picture, save and leave the FCK editor.
#The row in the lable editor now shows an <img>-tag which refers to your bar picture.
#Repeat the above described steps as often as needed to build up your bar scale.

==Doing a Likert Scale==

''Tested with: ''

A Likert Scale is a special type of the Semantic Differential question where several item shall be rated on different scales, each marked at the beginning and at the end with opposite statements. See example:

ttp://www.limesurvey.org/images/fbfiles/images/lickert.jpg

To do this in LimeSurvey just follow these steps:
#Create a label set with values from 0 to 7 (for the classic Likert Scale - feel free to choose other ranges).
#Create a new question and choose Array (Flexible Labels) as question type.
#Assign the Likert Scale label set to this question.
#Enter your answers as follows:

<syntaxhighlight lang="php" enclose="div"><DIV style="white-space: nowrap;">ITEM statement1|statement2</div></syntaxhighlight>

The white-space style is to avoid line breaks which would ruin the whole scale. feel free to insert non-breakable spaces between the ITEM and statement1 to define the margin between these to strings.

==Alternate background colour of questions==

''Tested with: 1.85+ (7191)''

To alternate the background colour of questions, open the ''template.css'' of your template with the Template Editor or a text editor and modify the ''Question styles'' section to include the following style.

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

div#question2 td.questiontext,

div#question4 td.questiontext,

div#question6 td.questiontext {

background-color: #E0EBF8;

}

</syntaxhighlight>

Be sure to apply the style to all of the questions you would like modified using their question IDs (''question2, question4, question6'' in this case). Question IDs are displayed when creating or editing questions - see below:

[[File:qid_1_493x173.gif]]

Here are links to a couple of screenshots - [http://www.limesurvey.org/images/fbfiles//images/questionBgColourBefore_750x550.gif before] the styles change and [http://www.limesurvey.org/images/fbfiles//images/questionBgColourAfter_750x550.gif after]. The darker blue (#E0EBF8 in the "after" shot) is kinda subtle but could be more pronounced with something like #BACFEB.

==Embedding audio in questions==

''Tested with: 1.85+ (7191), IE 7, FireFox 3''

Audio clips can be embedded in most question text or answer text. In this example, using the default template, I've embedded clips into the answers of an '''''Array (Yes/No/Uncertain)''''' question to ask respondents how they feel about some sounds. The resulting question will look like this.

[[File:audioTest_595x202.gif]]

It's accomplished by placing the following code in each of the answers.

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

<embed height="20" width="128" autostart="false" controls="console"

loop="true" volume="50" src="{TEMPLATEURL}audio_1.mp3"></embed>

</syntaxhighlight>

Some notes about the code:
*The ''audio_1.mp3'' part will be different for each answer (it's the audio file name).
*In this case the audio files are residing in the template folder being used for this survey (that's where ''{TEMPLATEURL}'' points to) but they can be placed anywhere if you use an absolute URL in the ''src'' parameter - something like ''src="http://mysite.com/audio/audio_1.mp3"''
*If the audio file doesn't exist where the ''src'' parameter indicates, the player will not appear.
*You'll need to insert the code into the answers using the source screen - click on "Edit answers", click the pencil beside the text box, click "Source" in the pop-up, enter the code and save it with the little diskette icon.
*You may need to turn off the XSS filter - see the documentation for [http://http://docs.limesurvey.org/tiki-index.php?page=Optional+settings&highlight;=filterxsshtml#Security Configuration Optional Settings / Security].

Although the above example places the audio in the answer text of the question, the same principles can be used to place it in the question text itself. Something like this perhaps.

[[File:audioTest_595x154.gif]]

==Hiding inputs of a "Multiple options with comments" question==

Tested with: 1.85+ (7253), IE 6/7, FireFox 3.0, Safari 3.2, Chrome 2.0

There may be times when you want to hide some of the input boxes of a '''''Multiple options with comments''''' question as in the image below.

[[File:hidden_inputs_541x168.gif]]

This can be accomplished with CSS (see [http://docs.limesurvey.org/tiki-index.php?page=Template+editor&structure;=English+Instructions+for+LimeSurvey#Styling_questions_in_LimeSurvey_1.8 Styling questions in LimeSurvey 1.8]). For each input that you want to hide, add the following style to your template.css file:

<syntaxhighlight lang="php" enclose="div">
#answer11111X22X33Acomment {

display: none;

}

</syntaxhighlight>Where 11111 is your survey ID, 22 is your group ID, 33 is your question ID and A is the answer code.

Note that you will still see columns for the hidden inputs in your data but they will be empty.

== Multiple question types in array==

''Tested with: 1.85+ (7557), IE 6/7, Firefox 3.0, Safari 3.2 (Yes/No question styles need tweaking in Safari)''

This workaround allows you to present multiple question types in what appears to be an array - as depicted in the image below and [http://www.partnersinc.biz/surveys//index.php?sid=52381&newtest;=Y&lang;=en demonstrated here]. This example uses the default template shipped with 7557 but should be adaptable to any template using divisions for question containers.

[[File:inline_questions_700x228.png]]

Basically what we do is take groups of questions (5 in this case), wrap them in a division and make them line up nicely horizontally and vertically. The width of the survey is also fixed to prevent wrapping issues. We do this with an onload function that inserts the necessary wrappers and then modifies styles so everything behaves properly. The top row is 5 boilerplate questions with the "column headers" as question text (the first just has a blank space). The following rows are a boilerplate with the "row headers" followed by 4 assorted questions.

Implementation is as follows:
#Turn off ''$filterxsshtml'' to allow insertion of JavaScript in the questions (see [http://docs.limesurvey.org/tiki-index.php?page=Optional+settings&structure;=English+Instructions+for+LimeSurvey#Filtering_dangerous_HTML_tags_in_survey_objects documentation here]).
#Set up the template to use custom onload functions (see the [http://docs.limesurvey.org/tiki-index.php?page=Workarounds&structure;=English+Instructions+for+LimeSurvey#Custom_onload_function workaround here]).
#Create your questions keeping in mind how they will lay out when grouped into rows (in this example - boilerplate, yes/no, short text, numeric, dropdown, and repeat).
#In the source of the first boilerplate question add the following onload function (see [http://docs.limesurvey.org/tiki-index.php?page=Workarounds&structure;=English+Instructions+for+LimeSurvey#How_to_use_Script_eg._JavaScript_etc._ How to use script here]).
#Modify the question IDs in the first section of the code to match your survey.

The code may look intimidating at first but it's actually fairly simple. I've layed it out as sequentially as possible and purposely used few shortcuts and many comments to make it easier to follow.

Some brief notes about the code:
#The first section just assigns attributes to questions so we can handle them as rows or columns later - in this case 190-194 are row 1 (the top boilerplates), 195-199 are row 2, etc.
#The second section fixes the width of the survey (not necessary with fixed-width templates), inserts wrapper elements around each group of questions (rows) and forces each group to display horizontally.
#The next section adjusts column widths.
#The final section applies styles to the different question types to hide unnecessary elements and ensure that vertical alignment, question height, etc are consistent.

Onload code:

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

<script type="text/javascript" charset="utf-8">

function Custom_On_Load(){

$(document).ready(function() {

/***********

Display multiple questions side by side

***********/

//////// Define question attributes for later use ////////

// Give questions row specific attributes so we can easily manipulate them by row

$('#question190, #question191, #question192, #question193, #question194').attr('name', 'qRow1');

$('#question195, #question196, #question197, #question198, #question199').attr('name', 'qRow2');

$('#question200, #question201, #question202, #question203, #question204').attr('name', 'qRow3');

$('#question205, #question206, #question207, #question208, #question209').attr('name', 'qRow4');

// Give questions column specific attributes so we can easily manipulate them by column

// I know, not the correct use of "rel" attribute but...too bad!

$('#question190, #question195, #question200, #question205').attr('rel', 'qCol1');

$('#question191, #question196, #question201, #question206').attr('rel', 'qCol2');

$('#question192, #question197, #question202, #question207').attr('rel', 'qCol3');

$('#question193, #question198, #question203, #question208').attr('rel', 'qCol4');

$('#question194, #question199, #question204, #question209').attr('rel', 'qCol5');

//////// Survey layout manipulation ////////

// Fix the width of the survey

$( 'table.outerframe' ).css({

'width': '900px'

});

// Wrap each row in a div

// This is kinda verbose but IE won't let me use jQuery shortcuts

var el = document.createElement('div');

el.setAttribute('id','inlineWrapper1');

document.body.appendChild(el);

$('div[name="qRow1"]').wrapAll($('#inlineWrapper1'));

el.setAttribute('id','inlineWrapper2');

document.body.appendChild(el);

$('div[name="qRow2"]').wrapAll($('#inlineWrapper2'));

el.setAttribute('id','inlineWrapper3');

document.body.appendChild(el);

$('div[name="qRow3"]').wrapAll($('#inlineWrapper3'));

el .setAttribute('id','inlineWrapper4');

document.body.appendChild(el );

$('div[name="qRow4"]').wrapAll($('#inlineWrapper4'));

// Style the wrapper divs

$( '#inlineWrapper1, #inlineWrapper2, #inlineWrapper3, #inlineWrapper4' ).css({

'width': '850px',

'margin': '0 auto 0 auto',

'clear': 'both'

});

// Get all the questions to sit politely side by side

$( 'div[name="qRow1"], div[name="qRow2"], div[name="qRow3"], div[name="qRow4"]' ).css({

'float': 'left',

'display': 'inline'

});

//////// Column manipulation ////////

// Set the column widths - can be set individually if necessary

// Must add up to less than 100%

$( 'div[rel="qCol1"]' ).css({

'width': '12%'

});

$( 'div[rel="qCol2"], div[rel="qCol3"], div[rel="qCol4"], div[rel="qCol5"]' ).css({

'width': '22%'

});

//////// Question manipulation ////////

// Hide the answer element in boilerplate questions

$( 'div.boilerplate td.answer' ).parent().hide();

// Hide the question text elements in non-boilerplate questions

$('div.text-short td.questiontext, div.list-dropdown td.questiontext,

// CAUTION: Manually introduced line break, should be "...td.questiontext, div.yes-no td.questiontext, ...

div.yes-no td.questiontext, div.numeric td.questiontext').parent().hide();

// Push the question tables to 100%

$( 'div[name="qRow1"] table, div[name="qRow2"] table, div[name="qRow3"] table, div[name="qRow4"] table' ).css({

'width': '100%'

});

// Get everything to line up nicely vertically

$( 'td.questiontext, td.answer p' ).css({

'text-align': 'center'

});

// Adjust cell heights so everything lines up nicely horizontally

$( 'td.answer, td.questiontext' ).css({

'height':'35px'

});

// Yes-no question styles

$( 'div.yes-no ul' ).css({

'text-align': 'center',

'font-size': '90%',

'margin': '0',

'padding-bottom': '5px'

});

$( 'div.yes-no td.answer' ).css({

'padding-bottom': '0'

});

// Short-text question styles

$( 'div.text-short input' ).css({

'width': '125px',

'margin-left': '0'

});

// Numeric question styles

$( 'div.numeric input' ).css({

'width': '125px',

'margin-left': '0'

});

$( 'div.numeric p.tip' ).css({

'display': 'none'

});

// Get rid of the margins around select boxes

$( 'p.question' ).css({'margin':'0'});

// Reduce the space caused by the question help table

$( 'div[name="qRow1"], div[name="qRow2"], div[name="qRow3"]' ).css({

'margin-bottom': '-8px'

});

});

}

</script>

</syntaxhighlight>

== Star Rating System==

''Tested with: 1.85+ (7557), IE 6/7, FireFox 3.0, Safari 3.2,''

This workaround uses the [http://www.fyneworks.com/jquery/star-rating/ jQuery Star Rating Plugin] to display a series of stars that are used to generate a rating value. This value is then passed to either a hidden numeric input question or a hidden list radio question. Both methods are outlined below - use one or both depending on whether you want to use [http://docs.limesurvey.org/tiki-index.php?page=Assessments&structure;=English+Instructions+for+LimeSurvey assessments].

The plugin uses a series of radio inputs to generate the stars (more about these below). It allows the use of whole or partial stars as shown in [http://www.partnersinc.biz/surveys//index.php?sid=47586&newtest;=Y&lang;=en this demo] and the image below.

[[File:star_rating_700x324.png]]

=== Star Rating System Using Numeric Input Question===

Use this method if you would like your rating data to be collected as a numeric value and don't want to use [http://docs.limesurvey.org/tiki-index.php?page=Assessments&structure;=English+Instructions+for+LimeSurvey assessments] - it's a little easier to implement. There is a demo [http://www.partnersinc.biz/surveys//index.php?sid=47586&newtest;=Y&lang;=en here] (first question).

'''Implementation is as follows:'''

1. Turn off ''$filterxsshtml'' to allow insertion of JavaScript in the questions. (See [http://docs.limesurvey.org/tiki-index.php?page=Optional+settings&structure;=English+Instructions+for+LimeSurvey#Filtering_dangerous_HTML_tags_in_survey_objects documentation here])

2. Set up the template to use custom onload functions. (See the [http://docs.limesurvey.org/tiki-index.php?page=Workarounds&structure;=English+Instructions+for+LimeSurvey#Custom_onload_function workaround here])

3. [http://www.fyneworks.com/jquery/star-rating/ Download the plugin] and place the following included files in your template folder:
*jquery.MetaData.js
*jquery.rating.css
*jquery.rating.js
*delete.gif
*star.gif

4. In the <head> section of your startpage.pstpl, add the following code to link to the files.

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

<script type="text/javascript" src="{TEMPLATEURL}jquery.rating.js" charset="utf-8"></script>

<script type="text/javascript" src="{TEMPLATEURL}jquery.MetaData.js" charset="utf-8"></script>

<link rel="stylesheet" type="text/css" href="{TEMPLATEURL}jquery.rating.css" />

</syntaxhighlight>

5. Create a numeric input question and then in the source of the question add as many radio inputs as star segments. For example, if you would like 5 stars, each with half-segments (as in the demo Q1), you would need 10 radio inputs and that would give rating values from 1-10.

Don't confuse these inputs with the actual question, they are just for the plugin's use.

At this point your question source code should look something like below. Make sure that all inputs have the same name. Each input must have the same title as value and these must be sequential. Don't worry about how all of this looks in the WSYSWYG editor - the plugin is going to hide these inputs and replace them with stars.

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

Q1 - Some question text here.<br /><br />

<div id="starContainer">

<input type="radio" class="star {split:2}" title="1" value="1" name="q1Rate" />

<input type="radio" class="star {split:2}" title="2" value="2" name="q1Rate" />

<input type="radio" class="star {split:2}" title="3" value="3" name="q1Rate" />

<input type="radio" class="star {split:2}" title="4" value="4" name="q1Rate" />

<input type="radio" class="star {split:2}" title="5" value="5" name="q1Rate" />

<input type="radio" class="star {split:2}" title="6" value="6" name="q1Rate" />

<input type="radio" class="star {split:2}" title="7" value="7" name="q1Rate" />

<input type="radio" class="star {split:2}" title="8" value="8" name="q1Rate" />

<input type="radio" class="star {split:2}" title="9" value="9" name="q1Rate" />

<input type="radio" class="star {split:2}" title="10" value="10" name="q1Rate" />

</div>

</syntaxhighlight>

6. A note on split stars. The stars in the above example are split in half by the ''{split:2}'' metadata. So if you don't want split stars, your inputs would look like:

'''<input type="radio" class="star" title="1" value="1" name="q1Rate" />'''

And stars split into third-segments would look like:

'''<input type="radio" class="star {split:3}" title="1" value="1" name="q1Rate" />'''

7. Finally, in the source of the question add the following onload function after your inputs. (See [http://docs.limesurvey.org/tiki-index.php?page=Workarounds&structure;=English+Instructions+for+LimeSurvey#How_to_use_Script_eg._JavaScript_etc._ How to use script here])

Some notes on the code:
*Replace "SSSSS", "GG", "QQ" in the function call at the end with the survey ID, group ID and question ID respectively.
*The code will hide the numeric input and pass the rating values into it as they are changed. If the rating is canceled the numeric input is nullified. If a respondent navigates away from the page then returns the code "remembers" the previous rating and displays the stars accordingly.
*If you want to apply it to more numeric questions on the same page simply add more calls with the appropriate IDs. (eg. handleRatingNumeric(11111, 22, 1); handleRatingNumeric(11111, 22, 2); ...) .

Onload code:

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

<script type="text/javascript" charset="utf-8">

function Custom_On_Load(){

$(document).ready(function() {

function handleRatingNumeric (sID, gID, qID) {

// Hide the numeric input

$('#question' + qID + ' td.answer').parent().hide();

// Get a previous rating (if any) and use it to initialize the star display

var rating = $('#answer' + sID + 'X' + gID + 'X' + qID + '').val();

if ( rating != '' ) {

$('#question' + qID + ' input.star').rating('select', rating);

}

// Listener on the star rating cancel element

$('#question' + qID + ' div.rating-cancel').click(function(event) {

// Nullify the rating if the Cancel element is clicked

rating = '';

$('#answer' + sID + 'X' + gID + 'X' + qID + '').val(rating);

});

// Listener on the star rating elements

$('#question' + qID + ' div.star-rating').click(function(event) {

// Find the value of the highest clicked star and pass it into the text input

$('#question' + qID + ' div.star-rating-on').each(function(i) {

rating = $(this).children('a').html( );

});

$('#answer' + sID + 'X' + gID + 'X' + qID + '').val(rating);

});

}

// Call the function for the numeric question

handleRatingNumeric (SSSSS, GG, QQ);

});

}

</script>

</syntaxhighlight>

=== Star Rating System Using List (Radio) Question===

Use this method if you would like to use [http://docs.limesurvey.org/tiki-index.php?page=Assessments&structure;=English+Instructions+for+LimeSurvey assessments]. There is a demo [http://www.partnersinc.biz/surveys//index.php?sid=47586&newtest;=Y&lang;=en here] (second question).

'''Implementation is as follows:'''

1. Turn off ''$filterxsshtml'' to allow insertion of JavaScript in the questions. (See [http://docs.limesurvey.org/tiki-index.php?page=Optional+settings&structure;=English+Instructions+for+LimeSurvey#Filtering_dangerous_HTML_tags_in_survey_objects documentation here])

2. Set up the template to use custom onload functions. (See the [http://docs.limesurvey.org/tiki-index.php?page=Workarounds&structure;=English+Instructions+for+LimeSurvey#Custom_onload_function workaround here])

3. [http://www.fyneworks.com/jquery/star-rating/ Download the plugin] and place the following included files in your template folder:
*jquery.MetaData.js
*jquery.rating.css
*jquery.rating.js
*delete.gif
*star.gif

4. In the <head> section of your startpage.pstpl, add the following code to link to the files.

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

<script type="text/javascript" src="{TEMPLATEURL}jquery.rating.js" charset="utf-8"></script>

<script type="text/javascript" src="{TEMPLATEURL}jquery.MetaData.js" charset="utf-8"></script>

<link rel="stylesheet" type="text/css" href="{TEMPLATEURL}jquery.rating.css" />

</syntaxhighlight>

5. Create a list (radio) question with the same amount of sequentially numbered answers as star ratings. For example, if you want 5 whole-stars, you would create 5 answers, as in the image below, and this would give you ratings from 1-5. Note that the "Codes" and "Answers" must be sequential numbers.

[[File:star_rating_700x156_v2.png]]

6. In the list (radio) question, set the [http://docs.limesurvey.org/tiki-index.php?page=Question+attributes&structure;=English+Instructions+for+LimeSurvey#hide_tip hide_tip] question attribute to 1

7. In the source of the question add as many radio inputs as star segments. So 5 whole-stars (as in the demo Q2), would need 5 radio inputs.

Don't confuse these inputs with the actual question, they are just for the plugin's use.

At this point your question source code should look something like below. Make sure that all inputs have the same name. Each input must have the same title as value and these must be sequential. Don't worry about how all of this looks in the WSYSWYG editor - the plugin is going to hide these inputs and replace them with stars.

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

Q2 - Some question text here.<br /><br />

<div id="starContainer">

<input type="radio" class="star" title="1" value="1" name="q2Rate" />

<input type="radio" class="star" title="2" value="2" name="q2Rate" />

<input type="radio" class="star" title="3" value="3" name="q2Rate" />

<input type="radio" class="star" title="4" value="4" name="q2Rate" />

<input type="radio" class="star" title="5" value="5" name="q2Rate" />

</div>

</syntaxhighlight>

8. A note on split stars. The stars in the above example are whole-stars. If you want them split you need to add metadata to the class - something like ''{split:2}''. So if you want half-stars your inputs would look like:

'''<input type="radio" class="star {split:2}" title="1" value="1" name="q1Rate" />'''

And stars split into third-segments would look like:

'''<input type="radio" class="star {split:3}" title="1" value="1" name="q1Rate" />'''

9. Finally, in the source of the question add the following onload function after your inputs. (See [http://docs.limesurvey.org/tiki-index.php?page=Workarounds&structure;=English+Instructions+for+LimeSurvey#How_to_use_Script_eg._JavaScript_etc._ How to use script here])

Some notes on the code:
*Replace "SSSSS", "GG", "QQ" in the function call at the end with the survey ID, group ID and question ID respectively.
*The code will hide the question radio buttons and toggle them as the rating values are changed. If the rating is canceled all question inputs are unchecked. If a respondent navigates away from the page then returns the code "remembers" the previous rating and displays the stars accordingly.
*If you want to apply it to more numeric questions on the same page simply add more calls with the appropriate IDs. (eg. handleRatingRadio(11111, 22, 1); handleRatingRadio(11111, 22, 2); ...) .

Onload code:

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

<script type="text/javascript" charset="utf-8">

function Custom_On_Load(){

$(document).ready(function() {

function handleRatingRadio (sID, gID, qID) {

// Hide the radio input

$('#question' + qID + ' td.answer').parent().hide();

// Get a previous rating (if any) and use it to initialize the star display

var rating = $('#question' + qID + ' input.radio[checked=true]').attr('value');

//if ( rating != '' ) {

if ( rating ) {

$('#question' + qID + ' input.star').rating('select', rating);

}

// Listener on the star rating cancel element

$('#question' + qID + ' div.rating-cancel').click(function(event) {

// Nullify the rating if the Cancel element is clicked

rating = '';

$('#question' + qID + ' input.radio').attr('checked', false);

});

// Listener on the star rating elements

$('#question' + qID + ' div.star-rating').click(function(event) {

// Find the value of the highest clicked star and pass it into the text input

$('#question' + qID + ' div.star-rating-on').each(function(i) {

rating = $(this).children('a').html( );

});

$('#question' + qID + ' input.radio[value=' + rating + ']').attr('checked', true);

});

}

// Call the function for the radio question

handleRatingRadio (SSSSS, GG, QQ);

});

}

</script></syntaxhighlight>

== Variable column widths in array==

''Tested with: 1.85+ (7557), IE 6/7, Firefox 3.0, Safari 3.2''

This workaround allows you to define all column widths of an array question - as shown in the image below and [http://www.partnersinc.biz/surveys//index.php?sid=26842&newtest;=Y&lang;=en demonstrated here]. This example uses the default template shipped with 7557 but should be adaptable to any template.

[[File:array_widths_701x226.gif]]

We use a custom onload function to remove all of the widths imposed by the core code and then insert our own.

'''Implementation is as follows:'''
#Turn off ''$filterxsshtml'' to allow insertion of JavaScript in the questions (see [http://docs.limesurvey.org/tiki-index.php?page=Optional+settings&structure;=English+Instructions+for+LimeSurvey#Filtering_dangerous_HTML_tags_in_survey_objects documentation here]).
#Set up the template to use custom onload functions (see the [http://docs.limesurvey.org/tiki-index.php?page=Workarounds&structure;=English+Instructions+for+LimeSurvey#Custom_onload_function workaround here]).
#Create the array question.
#In the source of the array question add the following onload function (see [http://docs.limesurvey.org/tiki-index.php?page=Workarounds&structure;=English+Instructions+for+LimeSurvey#How_to_use_Script_eg._JavaScript_etc._ How to use script here]).
#Replace all instances of QQ with the question ID.
#In the third section of code, adjust the widths and add/remove columns as necessary. This example is for an array with a question text column followed by 3 answer columns as shown above.
#In the final section adjust the question text alignment to your liking

Onload code

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

<script type="text/javascript" charset="utf-8">

function Custom_On_Load(){

$(document).ready(function() {

// Get rid of all the widths that the API imposes

$( 'div#questionQQ table.question col' ).attr('width', '');

$( 'div#questionQQ table.question thead td' ).attr('width', '');

// Define a width for the question table so we can do so for its children

// NOTE: Keep this to 95% or less so IE will behave

$( 'div#questionQQ table.question' ).attr('width', '95%');

// Define the column widths

// Add or remove columns and adjust widths as necessary but widths should add up to 100%

// NOTE: Columns must be sequentially numbered starting at 0 - eg, td:eq(0), td:eq(1), td:eq(2).....

$( 'div#questionQQ table.question tbody th:eq(0)' ).css({'width':'10%'}); // Answer text column

$( 'div#questionQQ table.question tbody td:eq(0)' ).css({'width':'50%'}); // First answer column

$( 'div#questionQQ table.question tbody td:eq(1)' ).css({'width':'20%'}); // Second answer column

$( 'div#questionQQ table.question tbody td:eq(2)' ).css({'width':'20%'}); // Third answer column

// Push the text input widths to 95% of their parent containers

$( 'div#questionQQ table.question input[type="text"]' ).css({'width':'95%'});

// Align the answer text - feel free to experiment

$( 'div#questionQQ table.question tbody th' ).css({'text-align':'center'});

});

}

</script></syntaxhighlight>

==Changing radio buttons and checkboxes==

''Tested with: 1.85 (7116), Googlechrome 3.0, IE 7, FireFox 3.0''

This workaround uses the jQuery imagetick.js to change the default radio buttons and checkboxes. Example:

[[File:screenshot.png]]

'''Implementation is as follows:'''

1. [http://docs.limesurvey.org/tiki-index.php?page=Optional+settings&structure;=English+Instructions+for+LimeSurvey#Filtering_dangerous_HTML_tags_in_survey_objects Turn off $filterxsshtml] to allow insertion of JavaScript in the questions.

2. Set up the template to [http://docs.limesurvey.org/tiki-index.php?page=Workarounds&structure;=English+Instructions+for+LimeSurvey#Custom_onload_function

|use custom onload functions].

3. Download the plugin [here|http://boedesign.com/download.php?file=imagetick] and place the following files in your template folder:
*imagetick.js
*check.gif
*no_check.gif
*no_radio.gif
*radio.gif

4. In the head section of your startpage.pstpl, add the following code to link to the files.

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

<head>

<script type="text/javascript" src="{TEMPLATEURL}imagetick.js"></script>

</head>

</syntaxhighlight>

5. In the source of the question [http://docs.limesurvey.org/tiki-index.php?page=Workarounds&structure;=English+Instructions+for+LimeSurvey#How_to_use_Script_eg._JavaScript_etc._

|add the following onload function] after your inputs:

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

<script type="text/javascript" charset="utf-8">

function Custom_On_Load(){

$(document).ready(function(){

// the selector can be a class as well, target your radios or checkboxes

$("input.radio").imageTick({

// the image you want to use as a selected state of the radio/checkbox

tick_image_path: "{TEMPLATEURL}radio.gif",

// image you want to use as a non selected state

// the class you want to apply to all images that are dynamically created

no_tick_image_path: "{TEMPLATEURL}no_radio.gif", image_tick_class: "radios"});

});

$("input.checkbox").imageTick({ // the selector can be a class as well

tick_image_path: "{TEMPLATEURL}check.gif",

no_tick_image_path: "{TEMPLATEURL}no_check.gif",

image_tick_class: "checkboxes"

});

}

</script>

</syntaxhighlight>

If you want to apply it to only one question on a page use selector

<syntaxhighlight lang="php" enclose="div">$("#questionQQ input.radio")</syntaxhighlight>

where QQ is the question ID

If you want to apply it to a single radio button in a question (to maybe have different images for each option) use selector

<syntaxhighlight lang="php" enclose="div">$("input#answerSSSSSXGGXQQAA")</syntaxhighlight>

where SSSSS is the survey ID, GG is the group ID, QQ is the question ID, AA is the answer code.

=Javascript=

==How to ''add'' javascript workarounds==

Well, this is pretty easy. Click the edit icon and create your own headline within the javascript section starting with "'''!!'''". Then add a short note about the version you have used when creating your workaround, you can copy/paste this code snippet <nowiki>''Tested with: (enter Limesurvey version and maybe browser)''</nowiki>.

Finally it's imported to mark all your code with code tags, other wise you might break this page.
*Start tag: '''<nowiki><syntaxhighlight lang="php" enclose="div"></nowiki>'''
*End tag: '''<nowiki></syntaxhighlight></nowiki>'''.

==How to ''use'' Script (eg. JavaScript etc.)==

If you want to use javascript within Limesurvey you previously have to disable a security filter before you can add your javascript in source code mode:

FIRST, some info from config-default.php:

<syntaxhighlight lang="php" enclose="div">//$filterxsshtml'''

// Enables filtering of suspicious html tags in survey, group, questions'''

// and answer texts in the administration interface'''

// Only set this to false if you absolutely trust the users'''

// you created for the administration of LimeSurvey and if you want to'''

// allow these users to be able to use Javascript etc. .'''

$filterxsshtml = true;</syntaxhighlight>

Follow these steps:
* In config.php add '''$filterxsshtml = false;''' (maybe as a last line before '''?>''').
* [http://docs.limesurvey.org/tiki-index.php?page=Adding+A+Question Add a new question]
* In the question field, expande the tool bar by clicking the upper grey bar to get to the [http://docs.limesurvey.org/tiki-index.php?page=First+Login+%2F+You+user+preferences&structure;=English+Instructions+for+LimeSurvey#The_HTML_editor_mode source code editor]:

[[File:InlineMode1.PNG]]
* Click on the button LimeFitWin to get full screen mode with even more buttons in the tool bar:

[[File:InlineMode2.PNG]]
* Click on the button Source

Now you can add your code. A simple test to see if javascript is enabled is to echo an alert. Use this code:

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

<script type="text/javascript" charset="utf-8">

alert("Test!");

</script>

</syntaxhighlight>

==Sum up input values using Javascript==

''Tested with: ''

This is from a survey that is a invitation to a longer party, when the user clicks to the next page, the calculated results will be shown.

If you wonder what the {INSERTANS:1X6X12} stuff is, look at [http://docs.limesurvey.org/tiki-index.php?page=SGQA+Identifier SGQA identifier] and [http://docs.limesurvey.org/tiki-index.php?page=Adding+a+Question#Information_from_previous_answers Using information from previous answers].

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

<div style="text-align: left">These are your answers:<br />

<u></u><u></u><u></u><u></u><u>=

<p><script LANGUAGE="JavaScript">

partyprice = 3;

beadclothprice = 3;

breakfastprice = 7;

lunchprice = 8;

dinnerprice = 10;

foodtotal = 0;

var isreallytrue = "Yes";

var noanswer = "No answer";

document.write( "Can you come? = {INSERTANS:45251X1X1}<BR>" );

if ("{INSERTANS:45251X1X1}" == isreallytrue )

{

if ("{INSERTANS:45251X1X3}"== noanswer) {answer = 0;}

else {answer = "{INSERTANS:45251X1X3}";}

partypeople = parseInt(answer);

partytotal = partyprice * partypeople;

document.write( "It's {INSERTANS:45251X1X3} persons who will come = " + partytotal + "€<BR>" );

if ("{INSERTANS:45251X1X4}"== noanswer) {answer = 0;}

else {answer = "{INSERTANS:45251X1X4}";}

beadcloths = parseInt(answer);

beadclothtotal = beadclothprice * beadcloths;

document.write( "You want to borrow {INSERTANS:45251X1X4} beadcloths = " + beadclothtotal + "€<BR>" );

document.write( "Will you be there thursday? = {INSERTANS:45251X1X5}<BR>" );

document.write( "On friday you will have these meals: <BR>" );

if ("{INSERTANS:45251X1X71}"== noanswer) {answer = 0;}

else {answer = "{INSERTANS:45251X1X71}";}

breakfastfriday = parseInt(answer) * breakfastprice;

document.write( "'''_ " + answer + " breakfeasts = " + breakfastfriday + "€<BR>" );

if ("{INSERTANS:45251X1X72}"== noanswer) {answer = 0;}

else {answer = "{INSERTANS:45251X1X72}";}

lunchfriday = parseInt(answer) * lunchprice ;

document.write( "'''_ " + answer + " lunches = " + lunchfriday + "€<BR>" );

if ("{INSERTANS:45251X1X73}"== noanswer) {answer = 0;}

else {answer = "{INSERTANS:45251X1X73}";}

dinnerfriday = parseInt(answer)* dinnerprice ;

document.write( "'''_ " + answer + " dinners = " + dinnerfriday + "€<BR>" );

foodtotal = breakfastfriday + lunchfriday + dinnerfriday;

document.write( "Will you be there saturday? = {INSERTANS:45251X1X8}<BR>" );

if ("{INSERTANS:45251X1X8}" == isreallytrue )

{

document.write( "On saturday you will have these meals: <BR>" );

if ("{INSERTANS:45251X1X91}"== noanswer) {answer = 0;}

else {answer = "{INSERTANS:45251X1X91}";}

breakfastsaturday = parseInt(answer) * breakfastprice ;

document.write("'''_ " + answer + " breakfeasts = " + breakfastsaturday + "€<BR>" );

if ("{INSERTANS:45251X1X92}"== noanswer) {answer = 0;}

else {answer = "{INSERTANS:45251X1X92}";}

lunchsaturday = parseInt(answer) * lunchprice ;

document.write( "'''_ " + answer + " lunches = " + lunchsaturday + "€<BR>" );

if ("{INSERTANS:45251X1X93}"== noanswer) {answer = 0;}

else {answer = "{INSERTANS:45251X1X93}";}

dinnersaturday = parseInt(answer) * dinnerprice ;

document.write( "'''_ " + answer + " dinners = " + dinnersaturday + "€<BR>" );

foodtotal = foodtotal + breakfastsaturday + lunchsaturday + dinnersaturday;

}

document.write( "Will you be there sunday? = {INSERTANS:45251X1X10}<BR>" );

if ("{INSERTANS:45251X1X10}" == isreallytrue )

{

document.write( "On sunday you will have these meals: <br>" );

if ("{INSERTANS:45251X1X111}"== noanswer) {answer = 0;}

else {answer = "{INSERTANS:45251X1X111}";}

breakfastsunday = parseInt(answer) * breakfastprice ;

document.write( "'''_ " + answer + " breakfeasts = " + breakfastsunday + "€<BR>" );

if ("{INSERTANS:45251X1X112}"== noanswer) {answer = 0;}

else {answer = "{INSERTANS:45251X1X112}";}

lunchsunday = parseInt(answer) * lunchprice ;

document.write( "'''_ " + answer + " lunches = " + lunchsunday + "€<BR>" );

if ("{INSERTANS:45251X1X113}"== noanswer) {answer = 0;}

else {answer = "{INSERTANS:45251X1X113}";}

dinnersunday = parseInt(answer) * dinnerprice ;

document.write( "'''_ " + answer + " dinners = " + dinnersunday + "€<p>" );

foodtotal = foodtotal + breakfastsunday + lunchsunday + dinnersunday;

}

total = partytotal + beadclothtotal + foodtotal;

document.write( "<h3>In total it will cost you " + total + "€</h3><BR>

Put that sum in this bank account 1234 5678 9012" );

}

</SCRIPT></p>

</div></syntaxhighlight>

==Multiple Question Validation==

''Tested with: ''

This workaround is in case you need to do some validation involving more than one question, it implies a very little JavaScript programming and the use of SQGA Identifiers; this should work on almost any version of LimeSurvey.

Is easy to explain with an example, we need to do a survey of the percentage of males and females and we want to be sure that the sum is 100, to do this follow this steps (the necessary data that is not indicated in these instructions are not important i.e. question codes, etc.):
#Create a new survey of type “group by group”, set the “Show |<< Prev| button” to yes and note the SID.
#Add a new group called “Group 1” and note the GID.
#Add a new question “Percent of males” of type “numeric”, make it mandatory and note the QID (we will refer to this as QID1).
#Add a new question “Percent of females” of type “numeric”, make it mandatory and note the QID (we will refer to this as QID2).
#Add a new group called “Group 2”
#Add a new non mandatory question, here is the trick the question text has to be (be sure to replace the SID, GID, QID1 and QID2

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

<script>

function validation()

{

if [[{INSERTANS:SIDXGIDXQID1}+{INSERTANS:SIDXGIDXQID2}) != 100)

{

alert("Your responses don't sum 100! Check them");

document.limesurvey.move.value = 'moveprev';

document.limesurvey.submit();

}

else

{

document.limesurvey.move.value = 'movelast';

document.limesurvey.submit();

}

}

setTimeout("validation()",250);

</script>

</syntaxhighlight>

But this will show shortly the question and will jump to the end page, a little weird for the survey taker but works.

This is a proof of concept, and may have some problems, please if you notice something or improve it send me an e-mail to leochaton-limesurvey at yahoo dot com.

This will work for 2 questions that you want to be the same. Works well for email and confirm email questions

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

function validation() {

if ("{INSERTANS:SIDXGIDXQID}" != "{INSERTANS:SIDXGIDXQID}") {

alert("Your responses don't match Check them"); document.limesurvey.move.value = 'moveprev';

document.limesurvey.submit();

}

}

setTimeout("validation()",250);

</syntaxhighlight>

==Alternate exit==

''Tested with: ''

Using the same idea of the previous post, you can implement an alternate exit of your survey.

This script should be in the first question to be displayed in a next page after the question that should trigger the alternate exit. In this example the question that trigger the alternate exit is a Yes/No question, if the user chooses no, he is redirected to another page.

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

<script>

if ("{INSERTANS:SIDXGIDXQID}" == "No")

{

window.location="http://www.limesurvey.org";

}

</script>

</syntaxhighlight>

==Custom onload function==

''Tested with: ''

This simple workaround describes how to '''add a custom onload function''' triggering when the page is being loaded. It may have numerous applications, especially when you deal with a custom JS/HTML code. It may be used to hide form elements (<input> tags), make them read-only, display alert messages, etc.

1. First, the template's of your choice "end page" code needs to be tweaked (it's in endpage.pstpl file). This is the only permanent change we'll be making here. Please note, that this change is harmless. Even if you are not gonna use any custom onload functions, it may stay there and it will not affect other surveys/questions in any way.

The modified content of your endpage.pstpl file should be as follows (~060~script~062~ section has been inserted):

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

</td>

</tr>

</table>

<script>

// only call if it's defined

if(typeof Custom_On_Load == 'function'){

Custom_On_Load();

}

</script>

</body>

</syntaxhighlight>

2. Now, if you define a function called "Custom_On_Load" anywhere in your code, it will be executed when the page is being loaded. For example when you add the following code to one of your question definitions:

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

<script>

function Custom_On_Load(){

alert('onload alert!');

}

</script>

</syntaxhighlight>It will display a pop-up message immediately after the page has been loaded.

Some of the applications of this trick I've explored are:

a) Hiding the form elements by calling in your Custom_On_Load:

<syntaxhighlight lang="php" enclose="div">document.getElementById("answer73166X16X54").style.display='none';</syntaxhighlight>

b) Making the elements read only:

<syntaxhighlight lang="php" enclose="div">document.getElementById("answer73166X16X54").readOnly=true;</syntaxhighlight> where the "answer73166X16X54" structure has been described in one of other workarounds above.

c) For Hiding by a lot of elements by calling in your Customer_On_Load

jQuery searchs in html document for input-fields with radio type, if his answer text empty then do the display css set to none.

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

jQuery(document).ready(

function() {

jQuery('input:radio').each(

function() {

var s = jQuery(this);

var c = s.parent().children('.answertext');

for(var i=0; i < c.length; i++) {

var a = jQuery(c[i]]);

if(this.id </u> a.attr('for') && a.text() == '') {

s.css({'display' : 'none'});

a.css({'display' : 'none'});

break;

}

}

}

)

}

);

</syntaxhighlight>

==Custom onload function in multi-language survey==

''Tested with: 1.85+ (7253), IE 6/7, FireFox 3.0, Safari 3.2,''

To use custom onload functions, as above, in multi-language surveys you must define the functions in the question source for '''all''' languages.

While this initially seems to be a bit tedious, it actually can be useful - you can alter your onload functions depending on the language in use. For example, you can dynamically display alerts or element contents in the current language.

==Advanced way for (global) custom onload function:==

This way, you can get one or more global onload functions, which will load on every page of your survey.

Define a function in startpage.pstpl before the closing head tag, or in template.js.

For example the focusFirst workaround function:

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

function focusFirst(Event)

{

var i=0;

while(document.forms[0].elements[i].type == "hidden")

{

i++;

}

document.forms[0].elements[i].focus();

return;

}

</syntaxhighlight>

Note that the "Event" Parameter is mandatory for functions added to an Event.

After defining the function which should be loaded, add this into the head tag of startpage.pstpl (or in template.js) :

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

if(ie)

{window.attachEvent("onload", functionName);}

else

{document.addEventListener("load", functionName, true);}

</syntaxhighlight>

var ie is set in startpage.pstpl to true (Internet Explorer) or false (other Browser than IE) with conditional comments. IE needs his own attachEvent.

EventListeners are supported from gecko and webkit Browsers (Firefox, Iceweasel, Safari, Chrome etc.)

==Global custom onload function in multi-language surveys==

''Tested with: 1.85+ (7253), IE 6/7, FireFox 3.0, Safari 3.2,''

Global custom onload functions can dynamically react to mid-survey language changes in multi-language surveys. This can be accomplished by using the value of the "languagechanger" element to control behavior of the onload function. It would be useful if you wanted to insert a language specific element or alerts on every question page of the survey. There is a small demo of this [http://www.partnersinc.biz/surveys//index.php?sid=77713&newtest;=Y&lang;=en|here].

In the demo we placed the following code at the very end of '''''endpage.pstpl'''''. The function will be called whenever a page loads and then checks to see if the language switcher exists (indicating that this is a question page and not the intro or thanks pages) and, if so, inserts an element with language specific text. The code could be easily modified to handle images or alerts.

Onload code

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

<script type="text/javascript" charset="utf-8">

function Custom_On_Load(){

// Don't do anything unless the document is fully loaded

$(document).ready(function() {

// Only continue if the language switcher is present on this page

if ( $('select.languagechanger').length > 0 ) {

// Check the value of the language switcher element to find the current language

var langChange = $('select.languagechanger').val();

var langArray = langChange.split('lang=');

var lang = langArray[1];

// Create some language specific text for the element that we'll insert below

var newElementText = '';

switch(lang) {

case 'en' :

newElementText = 'This element was inserted with a global onload function.';

break;

case 'fr' :

newElementText = "Cet élément ...<br />";

break;

case 'de-informal' :

newElementText = 'Dieses Element ...<br />';

break;

default :

break;

}

// Insert a div element and fill it with the text above

var el = document.createElement('div');

el.setAttribute('id','newElement');

document.body.appendChild(el);

$( '#newElement' ).css({

'border':'1px solid #333333',

'width':'50%',

'padding':'5px',

'color':'red',

'margin-bottom':'10px'

});

$('#newElement').html(newElementText);

$('.boilerplate').after($('#newElement']];

}

});

}

// Call the function

Custom_On_Load();

</script>

</syntaxhighlight>

==Skipping the welcome page==

''Tested with: 1.85 (second code snippet)''

'''Solution 1:''' Include this Javascript in your welcome template, file welcome.pstpl:

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

<script>

function custom_on_load(){

document.limesurvey.move.value = 'movenext';

document.limesurvey.submit();

}

window.onload = custom_on_load();

</script>

</syntaxhighlight>

It will reproduce the onclick event of the submit button and submit the form.

To assure that the function is called only after the whole page got loaded,

the window.onload event is used.

Drawback of course is that users will see the page flashing up.

Therefore, you may want to announce "... loading survey ..." as a description of your welcome page (in the admin interface when creating the survey), to pretend loading something big.

'''Solution 2:'''

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

<script>

function custom_on_load(){

document.limesurvey.move.value = 'movenext';

document.limesurvey.submit();

}

window.setTimeout( 'custom_on_load()',1);

</script>

</syntaxhighlight>

==Extend the use of Attribute1/Attribute2 to an unlimited number of attributes==

''Officially taken into the core at 1.85 (Tested with: 1.70)''

'''''Note'': This workaround is obsolute. Handling of additional tokens has been implemented in version 1.85. More information is available in the [http://docs.limesurvey.org/tiki-index.php?page=Tokens&structure;=English+Instructions+for+LimeSurvey#User_defined_attribute_fields manual].'''

User ''Schalburg'' created a javascript solution (based on release 1.70) to use more than the two standard attributes (Thanks for that!). The workaround is posted in the[http://bugs.limesurvey.org/view.php?id=1770 bug and feature tracker]. You'll find a detailled description there.

==Filter answers of a question with the answer of another==

''Tested with: 1.70 - 1.72''

If you want to filter the answer of a question with another answer, you can use this workaround.

First, use answer code like that: XX for the first question, and XXYYY for the second one.

Answer of the second question filter if the 2 first letters are the answer of the first question.

We use 1000X1X1 and 1000X1X2 for the example, question had to be on separate page (question by question for example).The second question had to be a dropdown list (we can do similar workaround, but droplis is the best)

Use the Custom_onload function:

<syntaxhighlight lang="php" enclose="div">function Custom_On_Load(){

var answerFilter='{INSERTANS:1000X1X1}' ;

var tblQuestionToFilter=document.getElementById('answer1000X1X2').options ;

var maxAnswer = tblQuestionToFilter.length;

var counter=1;

while (counter<=maxAnswer) {

if (![[(tblQuestionToFilter[counter].value).substr(0,answerFilter.length)==answerFilter)||

(tblQuestionToFilter[counter].value=="-oth-"]])

{

tblQuestionToFilter[counter]=null ;

maxAnswer--;

counter--;

}

counter++;

}

}

</syntaxhighlight>

==Use an answer to prefill another answer (default value)==

''Tested with: 1.72''

This workaround give you the ablility to use an answer to fill the default value for another answer. It's explai for free text question type but can be adapted for another question type.

We use SGQA identifier. For the exemple , we use SGQA 1000X10X20 and 1000X10X21 to prefill 1000X11X30 and 1000X11X31. For working, the question had to be on different page.

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

</script></syntaxhighlight>

==Dynamic Sum==

This script is used with a "Multiple Options" type question calculate a total price based on how which checkboxes are selected. The prices are listed as part of the answer. The answers are set up like this: "USB Mouse ($20)". The script uses the number between the "($" and the ")" as the price for that item. You can adapt the script to if you need to change the currency or need to sum something other than money.

This script works when used in a question-by-question format. It does not work when there are more than one question on a page. I think it can be adapted to work, but I haven't done the coding yet.

Put the following code into body of your question:

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

<script language=Javascript>

// General definitions

// Define a regular expression to match the labels containing information about an answer

// In LimeSurvey, these labels start with "answer..."

var answerRegex = /^answer/;

// Find all answer checkboxes in the document and set their

// onchange events to updatePrice

function Custom_On_Load()

{

// Find all input elements

var inputList=document.getElementsByTagName("input");

// Loop through each, looking for checkboxes

var i;

for( i=0; i< inputList.length;i++ )

{

// If input item does not have an ID, skip

if (! (inputList[i].id)) {continue;}

// Skip to next if ID doesn't start with "answer"

if (!answerRegex.test(inputList[i].id)) {continue;}

// Skip to next if not a checkbox

if (inputList[i].type.toUpperCase()!='CHECKBOX') {continue;}

// This is an answer checkbox!

// Setup onchange event

inputList[i].onclick = updatePrice;

}

// Load initial sum

updatePrice();

}

function updatePrice()

{

var labels=document.getElementsByTagName("LABEL");

// Define a regular expression to match a price inside parenthesis

// For example: ($29) or ($29.54).

// Set up

priceRegex = /$\$(\d*\.{0,1}\d+)$/;

// Loop through all the labels, looking for labels corresponding to

// answers that have a price in them.

var i;

var total = 0;

for( i=0; i<labels.length;i++ )

{

var myArray; // Define array used for regex matching

var inputID; // Define field element

// Get the ID of the field corresponding to the label using the

// "htmlFor" attribute

// (FYI, there are some labels that will have to be screened out

// because they don't correspond to an answer)

// Does the label start with "answer"?

// If not: exit.

if (!answerRegex.test(labels[i].htmlFor)) {continue;}

// First make sure this element exists

// If it doesn't, go to the next element

// If it does, it will be defined in inputID

if (! (inputID = document.getElementById(labels[i].htmlFor)) ) {continue;}

// See if the corresponding answer is a checkbox that is checked.

// If not, go to next label

if (inputID.type.toUpperCase()!='CHECKBOX') {continue;}

if (!inputID.checked) {continue;}

// This is label for an answer.

// The innerHTML will give us the text of the label

// The price information will be in the form ($XX.XX)

// which in contained in the label text.

// Find a match for a decimal number inside the pattern "($" and ")"

if [[myArray = priceRegex.exec(labels[i].innerHTML]] != null)

{

// Keep a running tally

total += parseFloat(myArray[1]);

}

}

// Update total price on form

document.getElementById("totalPrice").value = "$" + formatCurrency(total);

}

function formatCurrency(num) {

num = isNaN(num) || num <u> '' || num </u> null ? 0.00 : num;

return parseFloat(num).toFixed(2);

}

</script>

</syntaxhighlight>

Put the following code in the help section (or wherever you want the sum to appear):

<syntaxhighlight lang="php" enclose="div">Total Cost for selected accessories: <input type="readonly" value="" id="totalPrice" /></syntaxhighlight>

==Focus on the first Input field==

(''Tested with: Limesurvey 1.80 / IE6/7, Firefox 3, Safari, Opera, chrome'')

Again an onload Function is needed for this tasks. I have done it the DOM way with compatibility to IE6/7.

Put the following code into the startpage.pstpl of your template, right before the </head> closing tag:

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

<script type="text/javascript">

function focusFirst(Event)

{

var i=0;

while(document.forms[0].elements[i].type == "hidden")

{

i++;

}

document.forms[0].elements[i].focus();

return;

}

if(ie)

{window.attachEvent("onload", focusFirst);}

else

{document.addEventListener("load", focusFirst, true);}

</script>

</syntaxhighlight>

'''Note:''' I am using this with version 1.80. As changes happened to the templates in the last release, you might need to add the following before the code, if your template is older than 1.80 stable and does not include this:

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

<script type="text/javascript">

var ie = false;

</script>

</syntaxhighlight>

You will need this for the var ie to be set. Without this var, the function will not work with ie.

==Answer questions by keypress==

(''Tested with: IE7, Firefox 3'')

This workaround allow to answer the question on key 0-9 (0 is for the 10 answer).

Follow issues are supported at the moment:
*Yes-No Questions
*List Questions (radio)
*other radio questions

In lists the answer limit is ten.

You supply the template "endpage" of your template with the following script.

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

<script type="text/javascript">

jQuery(document).ready(function() {

jQuery(document).bind('keypress', function(e){

if (48 <= e.which && e.which <= 57) {

jQuery('input:radio').each(function() {

var v = jQuery(this).val();

var c = (e.which <u> 48) ? 10 : e.which - 48;

if(v </u> 'Y' || v <u> 'N') {

v = (v </u> 'Y') ? 1 : 2;

}

if(v == c) {

jQuery(this).click();

jQuery('#limesurvey input:submit').click();

}

});

}

})

});

</script>

</syntaxhighlight>

==Math notation in LimeSurvey==
#download the js file from [http://mathcs.chapman.edu/~jipsen/mathml/asciimathdownload.html AsciiMath script]
#copy it in the /scripts/ folder in your installation
#modify the startpage.psptl of the template you want to use adding the reference to the script (if you use an older version make sure that you copy the template folder first!) for example:

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

<script type="text/javascript" src="ASCIIMathML.js">

</syntaxhighlight>

Use the notation where you need it!

'''Note:''' If you use internet explorer or safari you will need to download the plugin as well, but firefox does the lot for you.

Finally, if you are confident with the limesurvey structure you could add the editor which support math notation and change the reference to the editor you want to use in the configuration file. here is the [http://www.imathas.com/editordemo/demo.html link for a TinyMCE with math support].

==Reverse array_filter==

''Tested with: 1.85+ (7253), IE 6/7, FireFox 3.0, Safari 3.2, Chrome 2.0''

This can be used to filter the answers of an array question to be displayed based on the answers of a multi option question that were '''NOT''' selected. A possible application would be to have a multi-option question asking which products were purchased, followed by 2 array questions - one asking to rate the purchased products and another asking why the remaining products were not purchased. Another would be to ask about sessions attended at a conference as in [http://www.limesurvey.org/en/support/forums/5-can-i-do-this-with-limesurvey/27970-reverse-of-arrayfilter.html this forum thread] and pictured below. There is a live [http://www.partnersinc.biz/surveys//index.php?sid=43358&newtest;=Y&lang;=en demo here]

[[File:sessions_645x344.gif]]

We'll use the above example to explain the process as follows:
#In group 1 - Create a ''SessionsAttended'' multi-options question
#In group 1 - Create a ''SessionsNotAttended'' multi-options question with identical answers as ''SessionsAttended'' and hide it with styles or conditions
#In group 2 - Create a ''RateSessionsAttended'' array question with an [http://docs.limesurvey.org/tiki-index.php?page=Question+attributes&structure;=English+Instructions+for+LimeSurvey#array_filter array_filter] based on ''SessionsAttended''
#In group 2 - Create a ''ReasonNotAttended'' array question with an [http://docs.limesurvey.org/tiki-index.php?page=Question+attributes&structure;=English+Instructions+for+LimeSurvey#array_filter array_filter] based on ''SessionsNotAttended''
#In group 1 - Place JavaScript/jQeury listeners on each of the checkboxes in ''SessionsAttended'' that would toggle the corresponding checkbox in ''SessionsNotAttended'' to the opposite state

The JavaScript/jQuery code used would be:

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

// The toggle function

function toggle(q1, q2) {

if ($(q1).attr('checked') == false ) {

$(q2).attr('checked', true);

}

else {

$(q2).attr('checked', false);

}

}

// Initialize the SessionNotAttended checkboxes to "checked"

toggle ('#answer11111X22X331', '#answer11111X22X441');

toggle ('#answer11111X22X332', '#answer11111X22X442');

toggle ('#answer11111X22X333', '#answer11111X22X443');

toggle ('#answer11111X22X334', '#answer11111X22X444');

// The jQuery listeners on the SessionAttended checkboxes

// that toggle the SessionNotAttended checkboxes

$('#answer11111X22X331').change(function() {

toggle ('#answer11111X22X331', '#answer11111X22X441');

});

$('#answer11111X22X332').change(function() {

toggle ('#answer11111X22X332', '#answer11111X22X442');

});

$('#answer11111X22X333').change(function() {

toggle ('#answer11111X22X333', '#answer11111X22X443');

});

$('#answer11111X22X334').change(function() {

toggle ('#answer11111X22X334', '#answer11111X22X444');

});

</syntaxhighlight>

Some notes about the code:
*The code is in an onload function defined in the first question of group 1 - see [http://docs.limesurvey.org/tiki-index.php?page=Workarounds&structure;=English+Instructions+for+LimeSurvey#Custom_onload_function workarounds here]
*Both ''SessionsAttended'' and ''SessionsNotAttended'' must be in the same group for the toggling to work
*This case only uses 4 checkboxes but could be expanded as required
*In this case the survey ID is 11111, the group ID is 22, ''SessionsAttended'' ID is 33 and SessionsNotAttended ID is 44 - these would need to be modified for your survey
*The toggle function looks for the state of a checkbox in ''SessionsAttended'' and sets the corresponding checkbox in ''SessionsNotAttended'' to the opposite state
*The "Initialize" section sets the state of ''SessionsNotAttended'' checkboxes whenever we navigate to the group
*The "Listener" section uses jQuery listeners to detect any change in the ''SessionsAttended'' checkboxes and then toggle the corresponding ''SessionsNotAttended'' checkbox

Some general notes about the questions:
*CSS can be used to hide ''SessionsNotAttended'' (div#question44 {display: none;}) if you don't want to use conditions (because maybe you've got [http://docs.limesurvey.org/tiki-index.php?page=Optional+settings&structure;=English+Instructions+for+LimeSurvey#Survey_Behavior $deletenonvalues set to 1])
*''RateSessionsAttended'' and ''ReasonNotAttended'' are another group to avoid things popping in and out of existence as ''SessionsAttended'' is answered
*[http://docs.limesurvey.org/tiki-index.php?page=Setting+conditions&structure;=English+Instructions+for+LimeSurvey Conditions] are used to ensure that ''RateSessionsAttended'' only appears if some sessions are selected and ''ReasonNotAttended'' only appears if no sessions are selected

==Auto-tabbing between text input fields==

''Tested with: 1.85+ (7253), IE 6/7, FireFox 3.0, Safari 3.2, Chrome 2.0''

This is a workaround to facilitate auto-tabbing between text input questions in a single group using a [http://plugins.jquery.com/project/autotab jQuery plugin by Mathachew] and the Maximum characters attribute of questions.

The behaviour will be: When the maximum number of characters has been entered into an input field, the focus (cursor) will be automatically moved to the next input field. When the backspace key is used to remove all characters from a field, the focus will be moved to the previous field. It's very useful in surveys having many text input questions to avoid having to manually tab or click between fields.

You can view a small demo survey [http://www.partnersinc.biz/surveys//index.php?sid=11327&newtest;=Y&lang;=en here].

Implementation is as follows:
#Visit [http://plugins.jquery.com/node/4046 http://plugins.jquery.com/node/4046], download the plugin script and save it as ''jquery.autotab-1.1b.js'' in the template folder.
#Link to the script by placing ''<script type="text/javascript" src="{TEMPLATEURL}jquery.autotab-1.1b.js"></script>'' within the ''<head>'' tag of startpage.pstpl.
#Turn off ''$filterxsshtml'' to allow insertion of JavaScript in the questions. (See [http://docs.limesurvey.org/tiki-index.php?page=Optional+settings&structure;=English+Instructions+for+LimeSurvey#Filtering_dangerous_HTML_tags_in_survey_objects documentation here])
#Set up the template to use custom onload functions. (See the [http://docs.limesurvey.org/tiki-index.php?page=Workarounds&structure;=English+Instructions+for+LimeSurvey#Custom_onload_function workaround here])
#Create the text based questions that auto-tabbing is to be applied to. (All must be in the same group if you're using group by group presentation)
#Define a Maximum characters attribute for all questions that the autotab is applied to. (See [http://docs.limesurvey.org/tiki-index.php?page=Question+attributes&structure;=English+Instructions+for+LimeSurvey#maximum_chars documentation here])
#In the first question of the group that contains the auto-tabbed questions, add the following code. (See [http://docs.limesurvey.org/tiki-index.php?page=Workarounds&structure;=English+Instructions+for+LimeSurvey#How_to_use_Script_eg._JavaScript_etc._ How to use script here]) Note: I prefer to use a boilerplate question for this and hide it with CSS - this prevents the JavaScript from appearing in error alerts etc.

Onload code:

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

<script>

function Custom_On_Load(){

$(document).ready(function() {

$('#answerSSSSSXGGXAA').focus(); //initially focus on the first input

$('#answerSSSSSXGGXAA').autotab({ target: 'answerSSSSSXGGXBB' });

$('#answerSSSSSXGGXBB').autotab({ previous: 'answerSSSSSXGGXAA', target: 'answerSSSSSXGGXCC' });

$('#answerSSSSSXGGXCC').autotab({ previous: 'answerSSSSSXGGXBB', target: 'answerSSSSSXGGXDD' });

$('#answerSSSSSXGGXDD').autotab({ previous: 'answerSSSSSXGGXCC' });

});

}

</script>

</syntaxhighlight>

This example has 4 fields to be auto-tabbed between - all instances of the following must be replaced to be compatible with your survey (See image below):
*SSSSS -> Survey ID
*GG -> Group ID
*AA -> First question
*BB -> Second question
*CC -> Third question
*DD -> Last question

[[File:ids_343x252.gif]]

The ''target'' parameter defines where the next input is and the ''previous'' parameter defines (you guessed it) the previous input.

This plugin also has limited capability of formatting the input text - see comments in the plugin script.

==Custom response listeners==

''Tested with: 1.85+ (7253), IE 6/7, FireFox 3.0, Safari 3.2, Chrome 2.0''

Listeners can be used to perform functions when a change in an input is detected. There are many uses such as the [http://docs.limesurvey.org/tiki-index.php?page=Workarounds#Reverse_array_filter Reverse array_filter] but a simple one would be to warn a respondent if they enter a value that may be too high.

We can use the [http://docs.jquery.com/Events/change jQuery change( ) event] to fire a function whenever there is a change to the input. The function will look for an input value higher than 10 and, if found, will warn the respondent.

Place the following code in your [http://docs.limesurvey.org/tiki-index.php?page=Workarounds#Custom_onload_function Custom onload function]:

Onload code:

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

$('#answer11111X22X33').change(function() {

if ( $('#answer11111X22X33').val() > 10 ) {

alert ("That's an awful lot. Are you sure?");

}

});

</syntaxhighlight>

Where:
*11111 is the survey ID
*22 is the group ID
*33 is the question ID

==Text input masks==

''Tested with: 1.85+ (7253), IE 7, FireFox 3.0, Safari 3.2, Chrome 2.0''

There may be instances where you would like to place a mask on a text input - for example only allowing respondents to enter the correct characters for a North American phone number [[###) ###-####) or a Canadian postal code (A1A 1A1) The [http://plugins.jquery.com/project/meioMask|jQuery meioMask plugin by fabiomcosta] can be used to do this.

The plugin has several pre-defined masks and supports custom masks. It also allows for pasting of input, allows default values and can auto-focus the next form element when the current input is completely filled. See [http://www.meiocodigo.com/projects/meiomask/|http://www.meiocodigo.com/projects/meiomask/] for more details on features and options.

You can view a small demo survey of masks in use [http://www.partnersinc.biz/surveys//index.php?sid=36146&newtest;=Y&lang;=en|here].

Implementation for this demo was as follows:

#Visit [http://www.meiocodigo.com/projects/meiomask/|http://www.meiocodigo.com/projects/meiomask/], download the latest plugin script and save it as ''jquery.meiomask.js'' in the template folder.

#Link to the script by placing ''<script type="text/javascript" src="{TEMPLATEURL}jquery.meiomask.js" charset="utf-8"></script>'' within the ''<head>'' tag of startpage.pstpl.

#Turn off ''$filterxsshtml'' to allow insertion of JavaScript in the questions. (See [http://docs.limesurvey.org/tiki-index.php?page=Optional+settings&structure;=English+Instructions+for+LimeSurvey#Filtering_dangerous_HTML_tags_in_survey_objects|documentation here])

#Set up the template to use custom onload functions. (See the [http://docs.limesurvey.org/tiki-index.php?page=Workarounds&structure;=English+Instructions+for+LimeSurvey#Custom_onload_function|workaround here])

#Create the text input questions that the masks are to be applied to

#In the first question of the group that contains the masked inputs, add the following code. (See [http://docs.limesurvey.org/tiki-index.php?page=Workarounds&structure;=English+Instructions+for+LimeSurvey#How_to_use_Script_eg._JavaScript_etc._|How to use script here]) Note: I prefer to use a boilerplate question for this and hide it with CSS - this prevents the JavaScript from appearing in error alerts etc.

Onload code:

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

<script>

function Custom_On_Load(){

$(document).ready(function() {

// Define custom masks

$.mask.masks = $.extend($.mask.masks,{

customMask1:{ mask: 'a9a 9a9' }, // Canadian postal code

// Maximum input of 9,999.99, reverse input, default value of 0.00

customMask2:{mask: '99.999,9', type : 'reverse', defaultValue : '000'}

});

// Set the 'alt' attributes of the inputs

$('#answer111111X22XAA').attr('alt', 'phone-us'); // a pre-defined mask

$('#answer111111X22XBB').attr('alt', 'customMask1'); // a custom mask

$('#answer111111X22XCC').attr('alt', 'customMask2'); // a custom mask

$('#answer111111X22XDD').attr('alt', 'cc'); // a pre-defined mask for credit card

// Tell the plugin to apply masks to these inputs

$('input:answer111111X22XAA').setMask();

$('input:answer111111X22XBB').setMask();

$('input:answer111111X22XCC').setMask();

$('input:answer111111X22XDD').setMask();

});

}

</script>

</syntaxhighlight>

The first section defines two custom masks to be used - one for Canadian postal code with a format of A#A #A# and a second for a maximum amount of 9999.99 with reverse input (useful for cost inputs) and a default value of 0.00.

The next section sets the "alt" attributes for the text inputs. This will tell meioMask which mask we will be applying to each input. By default meioMask looks at the alt attribute to find which mask to apply however this can be changed using the [http://www.meiocodigo.com/projects/meiomask/#mm_options|mask options].

In the final section we apply the masks to the inputs.

This example has 4 inputs with masks on them - all instances of the following must be replaced to be compatible with your survey (See image below):

*11111 -> Survey ID

*22 -> Group ID

*AA -> First question

*BB -> Second question

*CC -> Third question

*DD -> Fourth question

[[File:ids_343x252.gif]]

Oops, found a ''possible bug in IE6:'' You may need to paste the contents of jquery.meiomask.js into the very beginning of your custom onload function (before the document.ready function).

==Select a random response to a "Multiple options" question for later use==

''Tested with: 1.85+ (7253), IE 6/7, FireFox 3.0, Safari 3.2, Chrome 2.0''

This workaround allows you to randomly select one of the checked boxes in a "Multiple options" question and store it's label for later use in the survey. A possible use would be to have a question asking what products were purchased and then randomly selecting one of the products to ask further questions about.

There is a small demo of the above example [http://www.partnersinc.biz/surveys//index.php?sid=81252&newtest;=Y&lang;=en|here].

Basically what we've done here is to put listeners on all of the checkboxes. If a change of state is detected in any of them the "randomResponse" function is called which loops through all of the checkboxes and if it finds a checked state, that box's label is added to an array. Then a random item is pulled from the array and used to populate the hidden question. This hidden question can then be drawn upon later in the survey using [http://docs.limesurvey.org/tiki-index.php?page=Adding+a+Question#Information_from_previous_answers|INSERTANS] or [http://docs.limesurvey.org/tiki-index.php?page=Setting+conditions&structure;=English+Instructions+for+LimeSurvey|Conditions].

Implementation for this demo is as follows:

#Turn off ''$filterxsshtml'' to allow insertion of JavaScript in the questions. (See [http://docs.limesurvey.org/tiki-index.php?page=Optional+settings&structure;=English+Instructions+for+LimeSurvey#Filtering_dangerous_HTML_tags_in_survey_objects|documentation here])

#Set up the template to use custom onload functions. (See the [http://docs.limesurvey.org/tiki-index.php?page=Workarounds&structure;=English+Instructions+for+LimeSurvey#Custom_onload_function|workaround here])

#Create a "Multiple options" question that we're going to randomly pick a checked box from

#Create a text input question to store the label of the checked box in (we're going to hide this with JavaScript)

#In the first question of the group that contains the "Multiple options" question, add the following code. (See [http://docs.limesurvey.org/tiki-index.php?page=Workarounds&structure;=English+Instructions+for+LimeSurvey#How_to_use_Script_eg._JavaScript_etc._|How to use script here]) Note: I prefer to use a boilerplate question for this and hide it with CSS - this prevents the JavaScript from appearing in error alerts etc.

Onload code:

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

<script>

function Custom_On_Load(){

$(document).ready(function() {

//// Identify the hidden question input

//// EDIT HERE (1) - replace with your hidden question input ID

var hiddenInput = '#answer11111X22X44';

//// Make the "hidden" question disappear

//// EDIT HERE (2) - replace with your hidden question ID

$('#question44').hide();

//// Identify the checkboxes to be randomized

//// EDIT HERE (3) - add or remove as required,

//// replace with your checkbox IDs

var CB1 = '#answer11111X22X33A';

var CB2 = '#answer11111X22X33B';

var CB3 = '#answer11111X22X33C';

var CB4 = '#answer11111X22X33D';

var CB5 = '#answer11111X22X33E';

var CB6 = '#answer11111X22X33F';

//// Create an array of all checkboxes to be randomized

//// EDIT HERE (4) - add or remove CBs as required

checkBoxes = new Array( CB1, CB2, CB3, CB4, CB5, CB6 );

var checkBoxesLength = checkBoxes.length;

//// The randomizing function - no editing required

function randomResponse () {

var boxLabels = new Array();

// loop through all of the checkboxes and if they are checked,

// add their label to the boxLabels array

for( var i=0; i<checkBoxesLength; i++ ) {

if ( $(checkBoxes[i]).attr('checked') == true ) {

var cbid = checkBoxes[i].replace('#','');

boxLabels.push( $( 'label[for=' + cbid + ']' ).html() );

}

}

// find a random index of the responses array

var randomNum = Math.floor(Math.random() * boxLabels.length);

// populate the hidden question input with the

// random input value

$(hiddenInput).val( boxLabels[randomNum] );

}

//// The listeners that will fire the randomize function if a

//// change occurs in the checkboxes

//// EDIT HERE (5) - add or remove CBs as required

$(CB1).change(function() {

randomResponse ();

});

$(CB2).change(function() {

randomResponse ();

});

$(CB3).change(function() {

randomResponse ();

});

$(CB4).change(function() {

randomResponse ();

});

$(CB5).change(function() {

randomResponse ();

});

$(CB6).change(function() {

randomResponse ();

});

});

}

</script></syntaxhighlight>

The following edits are required to implement this in your survey:

*EDIT HERE (1) - 11111 -> Survey ID, 22 -> Group ID, 44 -> hidden question ID.

*EDIT HERE (2) - 44 -> hidden question ID.

*EDIT HERE (3) - 11111 -> Survey ID, 22 -> Group ID, 33 -> multiple option question ID, A/B/C/D/E/F -> multiple option answer codes. Also add or remove CBs for more or less checkboxes.

*EDIT HERE (4) - add or remove CBs for more or less checkboxes.

*EDIT HERE (5) - add or remove CBs for more or less checkboxes.

For more info on these IDs see [http://docs.limesurvey.org/tiki-index.php?page=SGQA+identifier&structure;=English+Instructions+for+LimeSurvey|SGQA identifier].

==Display secondary options in a "Multiple options" question==

''Tested with: 1.85+ (7253), IE 6/7, FireFox 3.0, Safari 3.2''

This workaround allows you to display secondary options in a "Multiple options" question if a primary option is checked as in the images below.

Primary option not selected:

[[File:secondary_options_1.jpg]]

Primary option selected:

[[File:secondary_options_2.jpg]]

There is a small demo of the above example [http://www.partnersinc.biz/surveys//index.php?sid=11491&newtest;=Y&lang;=en|here].

We've put a listener on the primary answer ("Option 1" in the demo) that shows or hides the secondary answers depending on the state of the primary.

Implementation for this demo is as follows:

#Turn off ''$filterxsshtml'' to allow insertion of JavaScript in the questions. (See [http://docs.limesurvey.org/tiki-index.php?page=Optional+settings&structure;=English+Instructions+for+LimeSurvey#Filtering_dangerous_HTML_tags_in_survey_objects|documentation here])

#Set up the template to use custom onload functions. (See the [http://docs.limesurvey.org/tiki-index.php?page=Workarounds&structure;=English+Instructions+for+LimeSurvey#Custom_onload_function|workaround here])

#Create a "Multiple options" question including both the primary and secondary answers (in the order that you would like them displayed if all shown)

#Add the following JavaScript to the onload function for that group (page). (See [http://docs.limesurvey.org/tiki-index.php?page=Workarounds&structure;=English+Instructions+for+LimeSurvey#How_to_use_Script_eg._JavaScript_etc._|How to use script here])

Onload code:

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

<script type="text/javascript">

function Custom_On_Load(){

$(document).ready(function() {

/****

The following code puts a listener on an answer in a multiple options

question (the primary answer) and if that answer is checked, a secondary

level of answers is displayed.

****/

// <strike>- 1 </strike>- Indent the secondary answers a bit

$( '#questionQQ li:eq(1)' ).css({'margin-left':'2.5em'});

$( '#questionQQ li:eq(2)' ).css({'margin-left':'2.5em'});

// <strike>- 2 </strike>- When the page loads, see if the primary answer is checked and if not,

//hide and un-check all secondary answers

if ($( '#answerSSSSSXGGXQQAA' ).attr('checked') == false ) {

$( '#questionQQ li:eq(1)' ).hide();

$( '#questionQQ li:eq(2)' ).hide();

$( '#answerSSSSSXGGXQQBB' ).attr('checked', false);

$( '#answerSSSSSXGGXQQCC' ).attr('checked', false);

}

// <strike>- 3 </strike>- Now put a listener on the primary answer to show or hide secondary answers

// We need to use .click instead of .change cause IE won't cooperate

$('#answerSSSSSXGGXQQAA').click(function (event) {

// Have a look at the primary answer and hide/show the secondary answers accordingly

if ($( '#answerSSSSSXGGXQQAA' ).attr('checked') == false ) {

$( '#questionQQ li:eq(1)' ).hide();

$( '#questionQQ li:eq(2)' ).hide();

$( '#answerSSSSSXGGXQQBB' ).attr('checked', false);

$( '#answerSSSSSXGGXQQCC' ).attr('checked', false);

}

else {

$( '#questionQQ li:eq(1)' ).show();

$( '#questionQQ li:eq(2)' ).show();

}

// The original functions of the click event

cancelBubbleThis(event);

checkconditions(this.value, this.name, this.type);

}

);

});

}

</script>

</syntaxhighlight>

'''''The following edits are required to implement this in your survey:'''''

'''Section 1:'''

*This section indents the secondary answers to give the look of a list in a list when they're shown

*'''QQ''' is your question ID

*'''eq(1)''' and '''eq(2)''' are the index positions of your secondary options. Modify or add as necessary for the number and placement of secondary options in your question. Note that the index starts at 0 so '''eq(1)''' actually affects the second option in the full list and '''eq(2)''' affects the third.

'''Section 2:'''

*This section checks the state of the primary question when the page is loaded and if necessary hides the secondary questions. We need this in case users navigate away from and then back to the page.

*Modify '''eq(1)''' and '''eq(2)''' as above.

*'''SSSSS''' is your survey ID.

*'''GG''' is your group ID.

*'''QQ''' is your question ID.

*'''AA''' is your primary answer code.

*'''BB''' and '''CC''' are your secondary answer codes (add as necessary).

'''Section 3:'''

*This is the section that "listens" to the primary answer and reacts accordingly.

*Edit as in section 2.

For more info on these IDs see [http://docs.limesurvey.org/tiki-index.php?page=SGQA+identifier&structure;=English+Instructions+for+LimeSurvey|SGQA identifier].

This code could be tidied up and shortened a bit but I left it this way to make it easier to follow.

== Generate random number to control survey behaviour==

''Tested with: 1.85+ (7253), IE 6/7, FireFox 3.0, Safari 3.2''

This workaround allows you to generate a random number and then populate a hidden question with that number. You can then use this question to control the display of subsequent questions with [http://docs.limesurvey.org/tiki-index.php?page=Setting+conditions&structure;=English+Instructions+for+LimeSurvey|Conditions]. It's useful if you have several sets of questions that you would like to randomly present to participants - see this [http://www.limesurvey.org/en/support/forums/5-can-i-do-this-with-limesurvey/29579-experiment-with-random-questions.html|forum post].

There is a small demo [http://www.partnersinc.biz/surveys//index.php?sid=12659&newtest;=Y&lang;=en|here].

In the demo, in the first group, we generate a random number between 1 and 4 and populate a hidden question with it. Then in the second group we have 4 questions, each showing conditional on the answer of the first question.

Implementation for this demo is as follows:

#Turn off ''$filterxsshtml'' to allow insertion of JavaScript in the questions. (See [http://docs.limesurvey.org/tiki-index.php?page=Optional+settings&structure;=English+Instructions+for+LimeSurvey#Filtering_dangerous_HTML_tags_in_survey_objects|documentation here])

#Set up the template to use custom onload functions. (See the [http://docs.limesurvey.org/tiki-index.php?page=Workarounds&structure;=English+Instructions+for+LimeSurvey#Custom_onload_function|workaround here])

#In the first group add a "Short free text" question (We're going to hide this with JavaScript)

#In the source of that question add the following onload function. (See [http://docs.limesurvey.org/tiki-index.php?page=Workarounds&structure;=English+Instructions+for+LimeSurvey#How_to_use_Script_eg._JavaScript_etc._|How to use script here])

#In the following groups add the questions that are conditional on the answer of the first question.

Onload code:

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

<script type="text/javascript">

function Custom_On_Load(){

$(document).ready(function() {

// Find a random number between 1 and 4

var randNumber = Math.floor(Math.random()*4 + 1);

// Populate and hide the hidden question

$('input#answerSSSSSXGGXQQ').val(randNumber);

$('#questionQQ').hide();

/***********************************************************/

// This just tells the user which number has been selected

// You can remove this from your onload function

$('input#setNumber').val(randNumber);

$('input#setNumber').css({

'margin-left':'0.5em',

'width':'1.5em',

'text-align':'center',

'font-weight':'bold'

});

$('input#setNumber').attr('disabled', true);

/***********************************************************/

});

}

</script>

</syntaxhighlight>

Where '''SSSSS''' is the survey ID, '''GG''' is the group ID and '''QQ''' is the hidden question ID.

Increase or decrease the maximum value of the random number by modifying the first section. For example to get a number between 1 and 10 you would use this:

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

var randNumber = Math.floor(Math.random()*10 + 1);

</syntaxhighlight>

The third section of code just populates a placeholder element that I use to tell the participant what's going on. You can remove it from your code.

== Minimum number of required answers in an array==

''Tested with: 1.85+ (7253), IE 6/7, FireFox 3.0, Safari 3.2,''

This workaround allows you to specify a '''minimum number''' of answers required in an array question. It is an alternative to the "Mandatory" parameter which specifies that '''all''' answers are required. It could also be easily modified to specify a maximum number of answers.

We accomplish this by placing an onload function in the source of the array question. This function hides the Next/Submit button and displays a warning element until it detects a minimum number of responses. It then hides the warning and shows the Next/Submit button.

There is a demo [http://www.partnersinc.biz/surveys//index.php?sid=97166&newtest;=Y&lang;=en|here].

Implementation is as follows:

#Turn off ''$filterxsshtml'' to allow insertion of JavaScript in the questions. (See [http://docs.limesurvey.org/tiki-index.php?page=Optional+settings&structure;=English+Instructions+for+LimeSurvey#Filtering_dangerous_HTML_tags_in_survey_objects|documentation here])

#Set up the template to use custom onload functions. (See the [http://docs.limesurvey.org/tiki-index.php?page=Workarounds&structure;=English+Instructions+for+LimeSurvey#Custom_onload_function|workaround here])

#In the source of the array question add the following onload function. (See [http://docs.limesurvey.org/tiki-index.php?page=Workarounds&structure;=English+Instructions+for+LimeSurvey#How_to_use_Script_eg._JavaScript_etc._|How to use script here])

#Modify the ''SETTINGS'' section of the code as required.

Onload code:

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

<script type="text/javascript" charset="utf-8">

function Custom_On_Load(){

// Wait until the document is fully loaded

$(document).ready(function() {

/********************** SETTINGS **********************/

// The text to appear in the warning element

var warningText = 'Please answer at least 4 to continue';

// The question ID

var questionId = 137;

// The minimum number of answers required

var minNumber = 4;

/******************************************************/

// Create the warning element and place it after the submit button

var el = document.createElement('div');

el.setAttribute('id','warning');

document.body.appendChild(el);

$( '#warning' ).css({

'border':'1px solid #333333',

'width':'200px',

'padding':'3px',

'color':'red'

});

$('#warning').html(warningText);

$('input[type="submit"]').after($('#warning']];

// Detect the initial number of checked answers & display Next/Submit button accordingly

var inputInitCount = 0;

$('#question' + questionId + ' input').each(function(i) {

if ($( this ).attr('checked') == true ) {

inputInitCount++;

}

});

if (inputInitCount > (minNumber - 1)) {

$('input[type="submit"]').show();

$('#warning').hide();

}

else {

$('#warning').show();

$('input[type="submit"]').hide();

}

// Listener to detect number of checked answers & display Next/Submit button accordingly

$('#question' + questionId + ' input').click(function() {

var inputCount = 0;

$('#question' + questionId + ' input').each(function(i) {

if ($( this ).attr('checked') == true ) {

inputCount++;

}

});

if (inputCount > (minNumber - 1)) {

$('input[type="submit"]').show();

$('#warning').hide();

}

else {

$('#warning').show();

$('input[type="submit"]').hide();

}

// The original functions of the click event

checkconditions(this.value, this.name, this.type);

});

});

}

</script>

</syntaxhighlight>

== Variable Length Array (Multi Flexible Text) question==

''Tested with: 1.85+ (7557), IE 6/7, FireFox 3.0, Safari 3.2''

This workaround allows a respondent to add or remove rows of an Array (Multi Flexible Text) question. It's useful to avoid the page being cluttered with unnecessary array rows.

An onload function is placed in the source of the array question. This function hides all of the array rows except the first and inserts two elements that when clicked show or hide rows accordingly.

There is a demo [http://www.partnersinc.biz/surveys//index.php?sid=53132&newtest;=Y&lang;=en here].

It must be noted that you can not make this question Mandatory as the respondent will have no way to complete hidden fields. If you want the displayed fields to be mandatory you will need to validate them in another function or modify this function to only allow the addition of rows if all fields in the last row are completed and then disable those fields - that, however, is a little over the top for this example.

Implementation is as follows:
#Turn off ''$filterxsshtml'' to allow insertion of JavaScript in the questions. (See [http://docs.limesurvey.org/tiki-index.php?page=Optional+settings&structure;=English+Instructions+for+LimeSurvey#Filtering_dangerous_HTML_tags_in_survey_objects documentation here])
#Set up the template to use custom onload functions. (See the [http://docs.limesurvey.org/tiki-index.php?page=Workarounds&structure;=English+Instructions+for+LimeSurvey#Custom_onload_function workaround here])
#Create one or more Array (Multi Flexible Text) questions
#In the source of the first array question add the following onload function. (See [http://docs.limesurvey.org/tiki-index.php?page=Workarounds&structure;=English+Instructions+for+LimeSurvey#How_to_use_Script_eg._JavaScript_etc._ How to use script here])
#Replace "QQ" in the function call at the end with the question ID.
#If you want to apply it to more arrays on the same page simply add more calls with the appropriate question IDs. (eg. varLengthArray(1); varLengthArray(2);...)

Onload code:

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

<script type="text/javascript" charset="utf-8">

function Custom_On_Load(){

$(document).ready(function() {

// A function to add or remove rows of an Array (Multi Flexible)(Text) question

function varLengthArray(qID) {

// The HTML content of the Add/Remove elements - modify as you wish

var addContent = '[+]';

var removeContent = '[-]';

// Just some initialization stuff

var arrayRow = '#question' + qID + ' table.question tbody tr';

var rowCount = '';

// Initially hide all except first row

$( arrayRow ).each(function(i) {

if ( i > 0 ) {

// We also need to give the hidden rows a name cause IE doesn't

// recognize jQuery :visible selector consistently

$( this ).attr('name', 'hidden').hide();

rowCount = i;

}

});

// Create the Add and Remove elements & insert them

var el1 = document.createElement('div');

el1.setAttribute('id','addButton');

document.body.appendChild(el1);

var el2 = document.createElement('div');

el2.setAttribute('id','removeButton');

document.body.appendChild(el2);

// Move them to after the array

$( 'div#addButton' ).appendTo($( '#question' + qID + ' td.answer' ));

$( 'div#removeButton' ).appendTo($( '#question' + qID + ' td.answer' ));

// Insert their HTML

$( 'div#addButton' ).html( addContent );

$( 'div#removeButton' ).html( removeContent );

// Style the elements - you can modify here if you wish

$( 'div#addButton' ).css({

'margin':'-10px 0 0 10px',

'padding':'1px',

'text-align':'center',

'font-weight':'bold',

'width':'auto',

'cursor':'pointer',

'float':'left'

});

$( 'div#removeButton' ).css({

'margin':'-10px 0 0 10px',

'padding':'1px',

'text-align':'center',

'font-weight':'bold',

'width':'auto',

'cursor':'pointer',

'float':'left'

});

// Initially hide the Remove element

$( 'div#removeButton' ).hide();

// Call the functions below when clicked

$( 'div#addButton' ).click(function (event) {

addRow();

});

$( 'div#removeButton' ).click(function (event) {

removeRow();

});

// Function to add a row, also shows the Remove element and hides the

//Add element if all rows are shown

function addRow() {

$( arrayRow + '[name="hidden"]:first' ).attr('name', 'visible').show();

$( 'div#removeButton' ).show();

if ( $( arrayRow + ':eq(' + rowCount + ')' ).attr('name') == 'visible' ) {

$( 'div#addButton' ).hide();

}

}

// Function to remove a row, also clears the contents of the removed row,

// shows the Add element if the last row is hidden and hides the Remove

// element if only the first row is shown

function removeRow() {

$( arrayRow + '[name="visible"]:last input[type="text"]' ).val('');

$( arrayRow + '[name="visible"]:last' ).attr('name', 'hidden').hide();

$( 'div#addButton' ).show();

if ( $( arrayRow + ':eq(1)' ).attr('name') == 'hidden' ) {

$( 'div#removeButton' ).hide();

}

}

}

// Call the function with a question ID

varLengthArray(QQ);

});

}

</script></syntaxhighlight>

== Partially Randomized Answers - Multiple Options & List (radio) questions==

''Tested with: 1.85+ (7557), IE 6/7, FireFox 3.0, Safari 3.2''

This workaround allows the answers of Multiple Options & List (radio) questions to be randomized while always keeping one answer at the end of the list. It's useful if you want to randomize, say, the first 4 of your answers but always have the fifth displayed last as in the image below:

[[File:random_336x179gif.gif]]

An onload function is placed in the source of a question. After the randomizing has occurred this function moves the answer with the highest answer code to the end of the list.

There is a demo [http://www.partnersinc.biz/surveys//index.php?sid=89344&newtest;=Y&lang;=en here].

Some conditions on the use of this are:
*For Select/radio type questions it will only work if the [http://docs.limesurvey.org/tiki-index.php?page=Optional+settings&structure;=English+Instructions+for+LimeSurvey#Survey_Behavior $shownoanswer option] is set to 0 in config.php. ("No answer" is removed from the end of questions)
*You must use sequential numbers, starting at 1 as response codes. (See image below)

[[File:random_700x154.png]]

Implementation is as follows:
#Turn off ''$filterxsshtml'' to allow insertion of JavaScript in the questions. (See [http://docs.limesurvey.org/tiki-index.php?page=Optional+settings&structure;=English+Instructions+for+LimeSurvey#Filtering_dangerous_HTML_tags_in_survey_objects documentation here])
#Set up the template to use custom onload functions. (See the [http://docs.limesurvey.org/tiki-index.php?page=Workarounds&structure;=English+Instructions+for+LimeSurvey#Custom_onload_function workaround here])
#Create one or more Multiple Options or List (radio) questions with sequential response codes. Set the [http://docs.limesurvey.org/tiki-index.php?page=Question+attributes&structure;=English+Instructions+for+LimeSurvey#random_order random_order question attribute] to 1.
#In the source of the first question add the following onload function. (See [http://docs.limesurvey.org/tiki-index.php?page=Workarounds&structure;=English+Instructions+for+LimeSurvey#How_to_use_Script_eg._JavaScript_etc._ How to use script here])
#Replace "SSSSS", "GG", "QQ" in the function call at the end with the survey ID, group ID and question ID respectively.
#If you want to apply it to more questions on the same page simply add more calls with the appropriate IDs. (eg. partRand(11111, 22, 1); partRand(11111, 22, 2); ...)

Onload code:

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

<script type="text/javascript" charset="utf-8">

function Custom_On_Load(){

$(document).ready(function() {

// Function to allow randomization of all answers

//except the last one in Multiple options and List/radio questions

function partRand(sID, gID, qID) {

// Find the number of answers

var ansCount = ''

$( 'div#question' + qID + ' td.answer li' ).each(function(i) {

ansCount = (i + 1);

});

// Place the last answer created at the end of the list

$( 'input#answer' + sID + 'X' + gID + 'X' + qID + ansCount + '' ).

//CAUTION: manually inserted line break.

//Append the line below at the end of the above one

parent().appendTo($( '#question' + qID + ' td.answer ul' ));

}

// Call the function with the SID, GID and QID

partRand(SSSSS, GG, QQ);

});

}

</script></syntaxhighlight>

== Partially Randomized Answers - List (dropdown) questions==

''Tested with: 1.85+ (7557), IE 6/7, FireFox 3.0, Safari 3.2''

This workaround, similar to the one above, allows the answers of List (dropdown) questions to be randomized while always keeping one answer at the end of the list. It's useful if you want to randomize, say, the first 4 of your answers but always have the fifth displayed last.

An onload function is placed in the source of a question. After the randomizing has occurred this function moves the answer with the highest answer code to the end of the list.

There is a demo [http://www.partnersinc.biz/surveys//index.php?sid=89344&newtest;=Y&lang;=en here].

A condition is that you must use sequential numbers, starting at 1 as response codes. (See image below)

[[File:random_700x154.png]]

Implementation is as follows:
#Turn off ''$filterxsshtml'' to allow insertion of JavaScript in the questions. (See [http://docs.limesurvey.org/tiki-index.php?page=Optional+settings&structure;=English+Instructions+for+LimeSurvey#Filtering_dangerous_HTML_tags_in_survey_objects documentation here])
#Set up the template to use custom onload functions. (See the [http://docs.limesurvey.org/tiki-index.php?page=Workarounds&structure;=English+Instructions+for+LimeSurvey#Custom_onload_function workaround here])
#Create one or more List (dropdown) questions with sequential response codes. Set the [http://docs.limesurvey.org/tiki-index.php?page=Question+attributes&structure;=English+Instructions+for+LimeSurvey#random_order random_order question attribute] to 1.
#In the source of the first question add the following onload function. (See [http://docs.limesurvey.org/tiki-index.php?page=Workarounds&structure;=English+Instructions+for+LimeSurvey#How_to_use_Script_eg._JavaScript_etc._ How to use script here])
#Replace "SSSSS", "GG", "QQ" in the function call at the end with the survey ID, group ID and question ID respectively.
#If you want to apply it to more questions on the same page simply add more calls with the appropriate IDs. (eg. partRandDD(11111, 22, 1); partRandDD(11111, 22, 2); ...)

Onload code:

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

<script type="text/javascript" charset="utf-8">

function Custom_On_Load(){

$(document).ready(function() {

// Function to allow randomization of all answers

//except the last one in List/dropdown questions

function partRandDD(sID, gID, qID) {

// Find the number of answers

var ansCount = ''

$( 'div#question' + qID + ' select option' ).each(function(i) {

ansCount = i;

});

// Place the last answer created at the end of the list

$( 'option[value="' + ansCount + '"]' ).appendTo($( 'div#question' + qID + ' select' ));

}

// Call the function with the SID, GID and QID

partRandDD(89344, 72, 244);

});

}

</script>

</syntaxhighlight>

== Making one (or more) rows of an array mandatory==

''Tested with: 1.85+ (7557), IE 6/7, Firefox 3.0, Safari 3.2''

This workaround allows you to define one or more rows of an array question as mandatory (instead of all of them which the "Mandatory" question setting does). It is [http://www.partnersinc.biz/surveys//index.php?sid=26842&newtest;=Y&lang;=en demonstrated here].

We use a custom onload function to interrupt the submit function and check if the inputs in the mandatory row(s) are populated. If not, an alert is popped up, the offending inputs are turned pink and the submit is aborted. Otherwise the submit goes ahead.

Implementation is as follows:
#Turn off ''$filterxsshtml'' to allow insertion of JavaScript in the questions (see [http://docs.limesurvey.org/tiki-index.php?page=Optional+settings&structure;=English+Instructions+for+LimeSurvey#Filtering_dangerous_HTML_tags_in_survey_objects documentation here]).
#Set up the template to use custom onload functions (see the [http://docs.limesurvey.org/tiki-index.php?page=Workarounds&structure;=English+Instructions+for+LimeSurvey#Custom_onload_function workaround here]).
#Create the array question.
#In the source of the array question add the following onload function (see [http://docs.limesurvey.org/tiki-index.php?page=Workarounds&structure;=English+Instructions+for+LimeSurvey#How_to_use_Script_eg._JavaScript_etc._ How to use script here]).
#Modify the alertText as required.
#Replace "QQ" with the question ID.
#Modify "tr:eq(0)" for whatever row you want mandatory. The row indexes start at 0, so "tr:eq(0)" would be row 1, "tr:eq(1)" would be row 2, "tr:eq(2)" would be row 3, etc. This example is for a single mandatory row - see below for multiple rows.

Onload code:

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

<script type="text/javascript" charset="utf-8">

function Custom_On_Load(){

$(document).ready(function() {

// Interrupt the submit function

$('form#limesurvey').submit(function(){

// The alert to be displayed - modify as required

var alertText = 'You must complete all fields for Option 1.';

var empty = 0;

// Loop through all inputs of the mandatory row

// Modify "tr:eq(0)" for the row to be mandatory (indexes start at 0)

// - eg, tr:eq(0) = row 1 mandatory, tr:eq(1) = row 2 mandatory,...

$( 'div#questionQQ table.question tbody tr:eq(0) input[type="text"]' ).each(function(i) {

if ( $( this ).val() == '' ) {

$( this ).css('background-color', 'pink');

empty = 1;

}

else {

$( this ).css('background-color', '#FFFFFF');

}

});

if ( empty == 1 ) {

alert ( alertText );

return false;

}

else {

return true;

}

});

});

}

</script></syntaxhighlight>

If you would like multiple mandatory rows, simply repeat the loop with the other row number(s) as below. This example would make rows 1 and 2 mandatory:

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

<script type="text/javascript" charset="utf-8">

function Custom_On_Load(){

<<strike>-</strike>---

// Loop through all inputs of the mandatory row

// Modify "tr:eq(0)" for the row to be mandatory (indexes start at 0)

// - eg, tr:eq(0) = row 1 mandatory, tr:eq(1) = row 2 mandatory,...

$( 'div#questionQQ table.question tbody tr:eq(0) input[type="text"]' ).each(function(i) {

if ( $( this ).val() == '' ) {

$( this ).css('background-color', 'pink');

empty = 1;

}

else {

$( this ).css('background-color', '#FFFFFF');

}

$( 'div#questionQQ table.question tbody tr:eq(1) input[type="text"]' ).each(function(i) {

if ( $( this ).val() == '' ) {

$( this ).css('background-color', 'pink');

empty = 1;

}

else {

$( this ).css('background-color', '#FFFFFF');

}

});

-->

}

</script>

</syntaxhighlight>

==Randomly displaying one of a few YouTube videos, and recording which was displayed==

''Tested in 1.85+''

Jason Cleeland has created and documented a method to randomly display one of a number of youtube videos in a single question, and save which one was displayed.

http://www.aptigence.com.au/home/archives/23-Random-display-of-videos-in-a-question-2-YouTube.html

=Survey Behavior=

==Respond multiple times using the same computer==

''Tested with: ''

With this workaround it will be possible to respond multiple times to the same survey. Normally there will be a message saying that the computer already received the answers. To prevent this you have to add the following code to the URL that leads to the survey ''"&newtest;=Y"''.

Example of the "new" url:

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

http://www.yourdomain.org/limesurvey/index.php?sid=12345&newtest;=Y

</syntaxhighlight>

==Allow Multiple Survey Invitations to the same Email Address to be completed in the Same Browser Session==

''Tested with: ''

'''Problem:''' When Multiple Surveys Invitations are activated during the same browser session, the second and subsequent survey activation results in a system message stating that the survey has already been completed. A user would have to close the browser and reopen in order to complete the next survey inviation.

'''Workaround:''' Edit the Survey Invitation Email (also the reminder) Template. Append "&newtest;=Y" to the {SURVEYURL} line so it looks like this {SURVEYURL}&newtest;=Y

Save the edited templates.

Note: The save of this template edit does not seem to work when using HTML invitations, only text based invitations.

==Add a data field to manually add data==

''Tested with: ''

If you want to add some additional data after a user has finished a survey you can use the dataentry screen of the admin panel. You have to set up the survey as follows:
# Create a question that can store the needed data at the end of the survey.
# Use [http://docs.limesurvey.org/tiki-index.php?page=Setting+Conditions conditions] on the previous question so that whatever is answered at the previous question the following question '''doesn't appear'''.
# To enter several questions repeat steps 1-2. Don't forget to adapt the conditions.
# Go to the admin panel, chose the survey from the list and go to ''Dataentry screen for survey''.
# Enter the additional data

==Totally random survey order==

''Tested with:''

If you want to use random order globally for all questions in your survey, you can do it like this, depending on what type of question routine you use.
# If you use Group by Group add "shuffle($_SESSION<nowiki>[</nowiki>'grouplist']);" at the end of UpdateSessionGroupList($language) function in index.php
# If you use Question by Question or All-in-one put "shuffle($_SESSION<nowiki>[</nowiki>'fieldarray'])" at the end of buildsurveysession() function in index.php

'''Important:''' This modifications affect all surveys in application, you may want to use an if statement with surveyid to make this work with specific surveys e.g.

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

if ($surveyid==12345)

{

do_some_shuffling()

}

</syntaxhighlight>
*Saving survey is not possible because this workaround doesn't save random order for specyfic tokens.
*Solution doesn't care about language changes so if you have on in your survey this will not work.
*Using conditions is not possible because conditions rely on a fixed and pre-determined order of questions.

==Selective group randomization==

''Tested with: 1.82''

Select which surveys you want to have their groups randomized, and not a global setting. This workaround puts a extra tab under group ordering which allows you to enable / disable group randomization for the selected survey.

A working code and database modification is described in the PDF file [http://bugs.limesurvey.org/file_download.php?file_id=1937&type;=bug selective_random_groups] which is downloadable from the Bugtracker at [http://bugs.limesurvey.org/view.php?id=3106].

'''Note:''' There may be situations where this might not work, for example when adding conditions or assessments to surveys.

==Randomize the order of ''sequences of groups'' in a survey==

''Tested with: 1.86''

You can randomize the order of subsequences of groups in a survey. E.g., you may have a survey comprising the below group structure
*demographics
*itemgroup1
*itemgroup2
*itemgroup3
*interlude
*itemgroup4
*itemgroup5
*itemgroup6
*closingcomments

and want to separately randomize the presentation order of itemgroup1...3 and itemgroup4...6 while maintaining the position of the other three groups. A working code modification is described in the PDF file [http://bugs.limesurvey.org/file_download.php?file_id=1228&type;=bug randomize_groups] which is downloadable from the Bugtracker at [http://bugs.limesurvey.org/view.php?id=557].
* '''Note:''' The code will randomize the order of subsequent groups in isolation, not across different sequences. Hence in the above example, you might get ''itemgroup1, 3, 2'' but never ''itemgroup1, 4, 2''
* '''Note:''' The survey presentation format must be ''Group by Group'' not ''Question by Question''
* '''Note:''' If you wish to select only a limited number of groups from a larger set, replace

<syntaxhighlight lang="php" enclose="div">$scratcharr = array_merge($scratcharr, $randarr);</syntaxhighlight>with

<syntaxhighlight lang="php" enclose="div">$scratcharr = array_merge($scratcharr, array_slice($randarr,0,x));</syntaxhighlight>

where x is the number of elements/groups that you wish to include. In the example above '''$scratcharr = array_merge($scratcharr, array_slice($randarr,0,2));''' would select two out of the possible three groups in each group set.
* '''Warning:''' The code is compatible with conditions operating on items within a group but most possibly produces erroneous behavior with conditions between groups
* '''Warning:''' In a multi-language survey, the groups get randomized each time the language is changed. A simple workaround is to remove the language changer from the question pages of the survey leaving it on the welcome page only. (Though not totally foolproof this does lower the risk of unnecessary language changes.)

==Selective Question Randomization==

''Tested with: 1.82''

With this workaround you are able to select which groups within a survey should have their questions randomized and not kept in order. This workaround also adds a tab in the question ordering page. The extra tab allows you to enable / disable question randomization for the selected group.

A working code and database modification is described in the PDF file [http://bugs.limesurvey.org/file_download.php?file_id=1939&type;=bug selective_random_questions] which is downloadable from the Bugtracker at [http://bugs.limesurvey.org/view.php?id=3107].

'''Note:''' This might not work when adding conditions or assessments to the survey.

== Randomize the order of questions within individual groups - JavaScript solution==

''Tested with: 1.85+ (7557), IE 6/7, Firefox 3.0, Safari 3.2''

This workaround allows you to randomize the order of questions in individual groups. It uses JavaScript/jQuery to apply this randomization to only those groups that you wish and requires no modification of the core files when updating the installation.

The script uses a cookie to "remember" the shuffled order of the questions for the duration of the session so if a respondent navigates away from the group and returns, they will see the same question order. However if the survey is submitted or the session expires the questions will be re-shuffled.

A couple of cautions about the script are:
#If the survey is saved, the questions will be re-shuffled when it is accessed again (as with the PHP solution).
#The question shuffling may play havoc with conditions within a group (as with the PHP solution).
#The script has been tested with all templates shipped with 1.85+ but if you have a custom template with "question" in the ID of division(s) (ie <div id="<span style='color:red'>question</span>Holder">) it may fail - the script looks for all divs with IDs starting with "question" and adds them to an array to be shuffled.

There is a small demonstration [http://www.partnersinc.biz/surveys//index.php?sid=84767&newtest;=Y&lang;=en here].

Put simply, the script:
#Checks cookies to see if the questions have already been shuffled for this group and session.
#If so - displays the questions in that order.
#If not - creates an array of all of the questions in the group, shuffles the array, sets a cookie with the shuffled array contents, displays the questions in the shuffled order.

Implementation is as follows:
#Turn off ''$filterxsshtml'' to allow insertion of JavaScript (see [http://docs.limesurvey.org/tiki-index.php?page=Optional+settings&structure;=English+Instructions+for+LimeSurvey#Filtering_dangerous_HTML_tags_in_survey_objects documentation here])..
#Create your group and questions.
#In the source of the group description add the following onload function (see [http://docs.limesurvey.org/tiki-index.php?page=Workarounds&structure;=English+Instructions+for+LimeSurvey#How_to_use_Script_eg._JavaScript_etc._ How to use script here]).

Onload code:

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

<script type="text/javascript" charset="utf-8">

$(document).ready(function() {

function shuffleQuestions() {

// Create an array to hold question IDs

var qArray = new Array();

// Find the group ID of the page

var fieldNames = $( 'input#fieldnames' ).attr('value');

var tmp = fieldNames.split('X');

var sID = tmp[0];

var gID = tmp[1];

// A function to get the value of a cookie by name

function getCookie ( cookieName ) {

var results = document.cookie.match ( '(<div class="simplebox">|;) ?' + cookieName + '=([</div>;]*)(;|$)' );

if ( results ) {

return ( unescape ( results[2] ) );

}

else {

return null;

}

}

// Get the session name

var sessionName = getCookie ( 'PHPSESSID' );

// Check to see if the question order has already been shuffled in this session

var cookieArray = getCookie ( 'sArray' + gID + '_' + sessionName );

// If already shuffled, use that question order

if ( cookieArray ) {

//qArray = $.trim(cookieArray);

qArray = cookieArray.split(',');

}

// If not, go ahead and shuffle

else {

// Load the IDs of all questions on the page into the array

$( 'div[id<div class="simplebox">="question"]' ).each(function(i) {

qArray.push($( this ).attr('id'));

});

// Shuffle the questions array

function shuffle(o){

for(var j, x, i = o.length; i; j = parseInt(Math.random() * i), x = o[--i], o[i] = o[j], o[j] = x);

return o;

}

shuffle(qArray);

// Set a cookie with the value of the shuffled array

var today = new Date();

today.setTime( today.getTime() );

var expires = 2 * 1000 * 60 * 60 * 24; // Expire the cookie in 2 days

var expiresDate = new Date( today.getTime() + (expires) );

document.cookie = 'sArray' + gID + '_' + sessionName + '=' + qArray + ';expires=' + expiresDate.toGMTString();

}

// Wrap the questions in a div

$( 'div[id</div>="question"]' ).wrapAll( document.createElement('div') );

$( 'div[id<div class="simplebox">="question"]:eq(0)' ).parent().attr('id', 'qWrapper');

$( 'div#qWrapper' ).css({

'padding':0,

'margin':0

});

// Insert the questions into the wrapper in the shuffled order

$.each(qArray, function(i, val){

$( 'div#' + val + '' ).appendTo( $( '#qWrapper' ) );

});

}

shuffleQuestions();

});

</script>

</syntaxhighlight>

== Randomise the order of questions ''within'' groups==

''Tested with: ''

You can randomize the order questions of within groups (i.e. without interleaving questions from different groups) like this:

1 Call a custom function from the last line of buildsurveysession() before the return statement in index.php:

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

$_SESSION<nowiki>[</nowiki>'fieldarray'] = withinGroupsShuffle();

</syntaxhighlight>

2. Add these custom functions at the end of the same file:

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

$currentGid;

function withinGroupsShuffle() {

global $currentGid;

$groupArray = array();

$shuffledArray = array();

foreach ($_SESSION['grouplist'] as $group) {

$currentGid = $group[0];

$groupArray = array_filter($_SESSION['fieldarray'], "questionInGroup");

shuffle($groupArray);

$tmp = $shuffledArray;

$shuffledArray = array_merge($tmp, $groupArray);

$groupArray = array();

}

return $shuffledArray;

}

function questionInGroup($question) {

global $currentGid;

return ($question[5] == $currentGid) ? 1 : 0;

}

</syntaxhighlight>

(''I'm new to PHP, so please make changes if you can make the code shorter or more elegant'')

This could be combined with the method mentioned above for shuffling the order of groups:

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

shuffle($_SESSION<nowiki>[</nowiki>'grouplist']);

</syntaxhighlight>

I don't know how this code affects or is affected by conditions or tokens! This code has the same limitations as the global randomisation above: it applies to all groups in all surveys. It would be nice to add a group-level parameter like randomise_questions = [0|1], but I can't find a mechanism for doing that.

== Random question sets==

''Tested with: 1.85+ (7557), IE 6/7, Firefox 3.0, Safari 3.2''

This workaround, in conjunction with the [http://docs.limesurvey.org/tiki-index.php?page=Workarounds#Randomize_the_order_of_questions_within_individual_groups_JavaScript_solution randomizing questions script], allows you to display a random set of questions in a group.

There is a small demonstration [http://www.partnersinc.biz/surveys//index.php?sid=84767&newtest;=Y&lang;=en here] (page 2).

JavaScript is used to first shuffle the question order and then hide the number of questions that you stipulate, effectively giving respondents a random question set. So if, as in the demo, you have 5 questions in your group and choose to hide 2, the respondents will be presented with a random 3 questions.

A brief explanation of the script is:
*The questions are shuffled (see [http://docs.limesurvey.org/tiki-index.php?page=Workarounds#Randomize_the_order_of_questions_within_individual_groups_JavaScript_solution randomizing questions]) and their IDs placed in an array.
*The number of questions to be shown is calculated and their IDs are moved to a new array.
*All questions in the first array are hidden - this effectively hides the first '''''n''''' questions on the page so you'll get a random set of questions displayed.
*An asterisk is prepended to the remaining questions (remove this if your questions are not mandatory).
*When the next/submit button is clicked, all remaining questions are checked for an answer. If any are unanswered, their text is turned red, an alert is popped up and the next/submit is aborted (remove this if your questions are not mandatory).

A cookie is used to "remember" the shuffled order of the questions for the duration of the session so if a respondent navigates away from the group and returns, they will see the same question set. However if the survey is submitted or the session expires, the questions will be re-shuffled and a new set will be displayed. Therefor this workaround should not be used with surveys that can be saved.

A couple of cautions about the script are:
#If the survey is saved, the questions will be re-shuffled when it is accessed again and a new question set will be displayed.
#The question shuffling may play havoc with conditions within a group.
#The script has been tested with all templates shipped with 1.85+ but if you have a custom template with "question" in the ID of division(s) (ie <div id="<span style='color:red'>question</span>Holder">) it may fail - the script looks for all divs with IDs starting with "question" and adds them to an array to be shuffled.
#The script may need to be modified to display the "Mandatory" asterisk in templates other than the default - see below.

Implementation is as follows:
#Turn off ''$filterxsshtml'' to allow insertion of JavaScript (see [http://docs.limesurvey.org/tiki-index.php?page=Optional+settings&structure;=English+Instructions+for+LimeSurvey#Filtering_dangerous_HTML_tags_in_survey_objects documentation here]).
#Create your group with all questions non-mandatory (we'll make them mandatory later with JavaScript).
#In the source of the group description add the following onload function (see [http://docs.limesurvey.org/tiki-index.php?page=Workarounds&structure;=English+Instructions+for+LimeSurvey#How_to_use_Script_eg._JavaScript_etc._ How to use script here]).
#Modify the function call at the end of the script for the number of questions to be hidden and the mandatory error text.

Onload code:

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

<script type="text/javascript" charset="utf-8">

$(document).ready(function() {

function shuffleQuestions() {

// Create an array to hold question IDs

var qArray = new Array();

// Find the group ID of the page

var fieldNames = $( 'input#fieldnames' ).attr('value');

var tmp = fieldNames.split('X');

var sID = tmp[0];

var gID = tmp[1];

// A function to get the value of a cookie by name

function getCookie ( cookieName ) {

var results = document.cookie.match ( '(</div>|;) ?' + cookieName + '=([<div class="simplebox">;]*)(;|$)' );

if ( results ) {

return ( unescape ( results[2] ) );

}

else {

return null;

}

}

// Get the session name

var sessionName = getCookie ( 'PHPSESSID' );

// Check to see if the question order has already been shuffled in this session

var cookieArray = getCookie ( 'sArray' + gID + '_' + sessionName );

// If already shuffled, use that question order

if ( cookieArray ) {

//qArray = $.trim(cookieArray);

qArray = cookieArray.split(',');

}

// If not, go ahead and shuffle

else {

// Load the IDs of all questions on the page into the array

$( 'div[id</div>="question"]' ).each(function(i) {

qArray.push($( this ).attr('id'));

});

// Shuffle the questions array

function shuffle(o){

for(var j, x, i = o.length; i; j = parseInt(Math.random() * i), x = o[--i], o[i] = o[j], o[j] = x);

return o;

}

shuffle(qArray);

// Set a cookie with the value of the shuffled array

var today = new Date();

today.setTime( today.getTime() );

var expires = 2 * 1000 * 60 * 60 * 24; // Expire the cookie in 2 days

var expiresDate = new Date( today.getTime() + (expires) );

document.cookie = 'sArray' + gID + '_' + sessionName + '=' + qArray + ';expires=' + expiresDate.toGMTString();

}

// Wrap the questions in a div

$( 'div[id<div class="simplebox">="question"]' ).wrapAll( document.createElement('div') );

$( 'div[id</div>="question"]:eq(0)' ).parent().attr('id', 'qWrapper');

$( 'div#qWrapper' ).css({

'padding':0,

'margin':0

});

// Insert the questions into the wrapper in the shuffled order

$.each(qArray, function(i, val){

$( 'div#' + val + '' ).appendTo( $( '#qWrapper' ) );

});

}

shuffleQuestions();

function hideQuestions(numberToHide, mandatoryMsg) {

// Create an array of the IDs of all questions on the page

var questions = new Array();

$( 'div[id<div class="simplebox">="question"]' ).each(function(i) {

questions.push($( this ).attr('id'));

});

// Remove the "shown" questions and place them in a new array

var questionsLength = questions.length;

var shownQuestions = questions.splice(numberToHide,questionsLength-numberToHide);

// Hide the remaining questions

$.each(questions, function(i, val){

$( 'div#' + val + '' ).hide();

});

// Add an asterisk to the "shown" questions

// NOTE: Comment this section out if questions are not mandatory

$( 'td.questiontext' ).prepend( '<span class="asterisk">*</span>');

// Interrupt the submit function and validate mandatory questions

// NOTE: Comment this section out if questions are not mandatory

$('form#limesurvey').submit(function(){

// Loop through all "shown" questions and check for answer

var answered = 0;

$.each(shownQuestions, function(i, val){

if ( $( 'div#' + val + ' input.radio:checked' ).length == 0 ) {

$( 'div#' + val + '' ).css('color', 'red');

answered = 1;

}

else {

$( 'div#' + val + '' ).css('color', '');

}

});

if ( answered == 1 ) {

alert ( mandatoryMsg );

return false;

}

else {

return true;

}

});

}

// Call the hide function

// Edit here for number of question to hide and mandatory message

hideQuestions(2, 'Please complete all questions');

});

</script>

</syntaxhighlight>

To add the asterisk to non default templates, replace ''$( 'td.questiontext' ).prepend( '<span class="asterisk">*</span>');'''' with:

- basic - ''$( 'td.be' ).prepend( '<span class="asterisk">*</span>');''

- bluengrey - Not possible to insert asterisk in correct location

- business_grey - ''$( 'div.questiontext' ).prepend( '<span class="asterisk">*</span>');''

- clear_logo - ''$( 'td.be' ).prepend( '<span class="asterisk">*</span>');''

- default - ''$( 'td.questiontext' ).prepend( '<span class="asterisk">*</span>');''

- eirenicon - Not possible to insert asterisk in correct location

- limespired - ''$( 'div.survey-question-text' ).prepend( '<span class="asterisk">*</span>');''

- mint_idea - ''$( 'div.survey-question-text' ).prepend( '<span class="asterisk">*</span>');''

- sherpa - ''$( 'div.survey-question-text' ).prepend( '<span class="asterisk">*</span>');''

- vallendar - Not possible to insert asterisk in correct location

==Randomization - ''Assign People Randomly'' To Surveys==

''Tested with: ''

This is a very easy way to assign people randomly to surveys, I think experts do it in other ways, but it works for me.

''LINK.PHP:''

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

$db = @file("link.txt"); // path to .txt file

$anz = @count($db);

srand[[SGQA identifier]], and the answer, as a parameter of your survey URL. This feature will only work where the survey is commenced immediately upon entering the URL (so it won't work if you use CAPTCHA's to restrict access, or the registration page).

You'll need to ensure that the answer you pass is the correct format for the question you are attempting to prefill - for example - multiple option questions should contain a "Y" to check a box. List type questions need the correct answer code. To be certain which codes to pass, complete a survey manually with the prefilled answer(s) you want, and then export the results as question codes and answer codes(not full text). This will give you both the correct SGQA identifier (the name of the column), and the correct format for the answer.

'''Example:'''

<div class="simplebox">http://www.myownd.../index.php?sid=1234&1234X43X123=Y</div>

When the user gets to that question, the "Y" will be prefilled as the answer to question 123 in group 43 in survey 1234.

==Prefilling survey answers using the survey URL and hiding the Answer==

''Tested with: 1.80RC3+''

Having used the previous workaround to prefill an answer in your survey by passing a [[SGQA identifier]] throught the URL, you may also want to hide the question that is being prefilled so that the user cannot modify it (or even know it is there).

There are currently two options for you:
*The javascript approach which does not require patching the limesurvey source
*Applying the patch attached to http://bugs.limesurvey.org/view.php?id=3555 and setting the ''hidden'' question attribute.

===The javascript approach===

To do this, utilise the id name of each answers div area. Each question is presented in a div with an idea comprising the word "question" immediately followed with the questions unique id code. So from the above example, with SGQA 1234X43X123, the question id we are prefilling is id 123. That means the div id for displaying the whole question is "question123".

To hide this question, enter the following javascript in the question source.

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

<script type='text/javascript'>

</script>

</syntaxhighlight>

This workaround will make most sense if you are displaying your surveys in groups. If you are displaying question by question, then the user will get a blank page with just a "Next" and "Prev" button, and they may get confused.

==Prefilling a date question with the current date==

''Tested with: 1.80RC3''

Workaround created by user "[http://docs.limesurvey.org/tiki-index.php?page=UserPage%20Mazi Mazi]"

Using the [http://docs.limesurvey.org/tiki-index.php?page=Workarounds#Prefilling_survey_answers_using_the_survey_URL workaround mentioned above] you can prefill the current date for a date question. Instead of using the common link to a survey which looks like this

<div class="simplebox">http://www.yourdomain.org/limesurvey/index.php?sid=53298&newtest;=Y&lang;=de</div>

you create an additional script, let's call it date.php. This script contains the following code:

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

<?php

$date = date("Y-m-d");

header("Location: http://www.yourdomain.org/limesurvey/index.php?sid=53298&newtest;=Y&lang;=de&53298X15X102=$date");

?>

</syntaxhighlight>

The script determines the current date and calls the survey with a certain URL. The current date is attached as the answer for a certain date question using [http://docs.limesurvey.org/tiki-index.php?page=SGQA+identifier SGQA identifier]. Don't forget to '''adjust the SID and SGQA identifier''' according to your survey/group/question ID!

Upload the new ''date.php'' file into your limesurvey directory. You can then call the survey using this link:

<div class="simplebox">http://www.yourdomain.org/limesurvey/date.php</div>

Things to watch out for:
* Date questions always use the internal date data format of the database which has to be YYYY-MM-DD!
* You have to adjust the SID at the URl.
* Also adjust the SGQA identifier (SIDXGIDXQID) according to your survey.
* This solution doesn't work if you use tokens at your survey.

''New:'' I created a PHP script which is easy to adapt by just entering the matching IDs. (''[http://docs.limesurvey.org/tiki-index.php?page=UserPage%20Mazi Mazi]'')

[[Media:prefill_date.php|Download this file]]

==Offer option to change answers later==

''Tested with: ''

When having a closed access survey using a token table it is possible to offer the opportunity to change answers later. Normally after having submitted the answers a token is marked as "used". To prevent this do as follows:
* set your survey to question-by-question mode (or group-by-group mode)
* set the survey to Non anonymous + Allow persistence for token answers
* activate survey and create your token table
* add at least one question of type boilerplate (which contains just some text). This is necessaray to give some instructions to the user like "''Your answers have been recorded to the DB, if you're sure you won't modify them, you can submit your response. If unsure, please quit your browser now and get back later with the private URL you've received''.

By not submitting the survey the user is still able to change the answers later.

==Use general password for accessing a survey==

If you don't want to use tokens but a general password to access a survey you can set your survey to "allow public access". Don't create a token table but use the following workaround:
# Create a short text question first
# Create the other questions
# Use conditions on all the other questions. You can use regular expressions to validate the string entered at the short text question. Just validate a certain password. If the password is correct the following questions are shown.
# Create a boilerplate question which just says "invalid password" which is shown if the user entered a wrong password.

==Create token on the fly and Edit completed survey==

When having a close token survey you can create a token on the fly by giving as parameters sid and token.

In addition if someone has already completed a survey he can review his answers and correct them.

[http://bugs.limesurvey.org/view.php?id=2982 Just put this script attached at the bugtracker ticket into limesurveys root directory]

'''Prerequisites''':
# Anonymous answers? No (This survey is NOT anonymous.)
# Enable Token-based answers persistence? Yes
# Switch to closed-acces mode

'''Example''':

<div class="simplebox">http://www.yoururl.com/limesurvey180/newtoken.php?sid=98761&token;=12345</div>

where Survey id = 98761 your survey's id and token=12345 a token (any token actually)
# The first time the token will be created and you you will redirect to anwser the surrvey
# If you wont complete the survey and call the script with the same parameters you will be redirect to the same case in order to finish the survey
# If you finish the survey and call the script with the same parameters you will see restart the survey with your previews answers prefiled so you can change them
# Back to 3

this is valid for all survey in the installation but you can make a filter so it wont be valid for every survey.

'''Relative posts'''
*LimeSurvey Bug & Feature Tracker

[http://bugs.limesurvey.org/view.php?id=2982]
*the code

http://bugs.limesurvey.org/file_download.php?file_id=1826&type;=bug

by user "janokary"

==multiple 'completed' with only one token==

''Tested with: 1.71''

Whit a closed survey, each token work only one time. Sometime we need the possibility to complete a particular survey several time with the same token.

Here is an example for the survey id '71314'. Don't forget to adapt your own sid.

Edit ''index.php '' to in the function submittokens() replace lines ~ 1312 :

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

if (bIsTokenCompletedDatestamped($thissurvey))

{

$utquery .= "SET completed='$today'\n";

}

}

else

{

$utquery .= "SET completed='Y'\n";

</syntaxhighlight>with lines :

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

if (bIsTokenCompletedDatestamped($thissurvey))

{

//multiple token only for survey 71314

if ($surveyid == '71314') {

$utquery .= "SET completed='N'\n";

}else {

$utquery .= "SET completed='$today'\n";

}

}

else

{

//$utquery .= "SET completed='Y'\n";

</syntaxhighlight>

We never update the database with the completed date and time for this survey.

'''Warning''' : a limitation of this code is that you never recieve a confirmation mail for the compledted.

==Loop question(s)==

''Tested with: 1.85''

There is no real loop option within Limesurvey 1.x. Too loop a question an initial question to determine the number of loops is needed. Looping is then done using a condition wokraround:

1. Create a single choice question asking "How many X do you want to rate", possible answers 1, 2, 3, 4, 5.

2. Create up to 5 following questions asking "Please rate item 1/2/3/...".

3. Check manual -> conditions and read it carefully.

4. Set conditions like

a) "Only show Q3 (Rate item 2) IF Q1 (How many...) was answered 2

OR Q1 (How many...) was answered 3

OR Q1 (How many...) was answered 4

OR Q1 (How many...) was answered 5"

b) "Only show Q4 (Rate item 3) IF Q1 (How many...) was answered 3

OR Q1 (How many...) was answered 4

OR Q1 (How many...) was answered 5"

c) Q5... see above

d) Q6...

Of course Q2 is always shown, the following question will be added by conditions depending on what the user answered at Q1.

=Improve Statistics=

==Display menu of all public survey statistics==

''Tested with: version 1.85''

Some of you may want to give your survey respondents a URL that will display a menu of all surveys that have public statistics to be displayed. This is a hack module that generates a menu only and then calls the real userstatistics module to display those statistics for your user.

It is a small file and is basically the same code Jason wrote to build the survey menu with some minor edits. You can rename the module to anything you like for your particular survey system and place it in your root directory. Then give the URL to this module to your users to produce a menu of the available surveys you have public statistics enabled on.

You can [http://www.limesurvey.org/support/forums/5-can-i-do-this-with-limesurvey/30067-display-menu-of-all-public-survey-statistics.html?lang=en#30067 download the file in the forum]

=Everything Else=

==How to import survey responses from v1.00 into v1.5x (and later)==

''Tested with: LS >= 1.50''

In LimeSurvey v1.50 it´s possible to import a survey, which is generated (and exported) with v1.00 into v1.5x. The Problem is, on that way only the survey structure gets imported, but no respones to that survey.

If you also need to import the responses, follow the next steps:
#Export your survey in v1.00
#Do a VV-Export in v1.00 (to save your responses)
#Import your survey from v1.00 into v1.5x via "Create or Import a New Survey" in the main Admin Panel
#Activate your imported survey
#Fill out your survey once, so that at least one response is in your database.
#Do a VV-Export in v1.5x
#Open both VV-Exports (v1.5x and v1.00); if you use Microsoft Excel do it via "Open New File" and "Import from Text-File" or "Import from external source - textfile" and choose "seperated" and "Unicode (UTF-8)"; choose
#Compare the file structure and you´ll see that there are two columns added (submitdate and startlanguage) and that all question codes changed.
#Copy all rows (except row 1 and 2, that means you start with the third row) from your VV-Export v1.00 into your VV-Export v1.5x (also put it at the third row)
#Add the columns "submitdate" and "startlanguage" in your VV-Export v1.5x-File, right between "id" and "token"
#Save your file (in Microsoft Excel use Textfile - Tabstopp seperated). It´s necessary that your file after saving has the same format as before - Notice: it´s not a normal .csv-File.
#Import your file via VV-Import

==If you closed your survey accidentally==

''Tested with: All versions''
# Activate your survey again
# Go to the "Browse responses for this survey" menu
# Click at the "Import answers from a deactivated survey table" button
# Choose your source table
# Click at the "Import responses" button

==Translate surveys without admin access==

''Tested with: ''

User "CasN" has written a nice extension that allows you to translate surveys without having access to the admin panel. He has added his files in the bug and feature tracker ([http://bugs.limesurvey.org/view.php?id=1735 01735: Remote translating feature]) where you can download them. You'll also find a short How-To there.

This is how it works:

Copy the scripts in the root of your survey directory and call starttrans.php like this starttrans.php?survey=12345

It will check the languages connected to the survey and also verify the labelsets used.

You will then get a screen with for each language the required links for translating, aswell for the labels as the survey itself. From the survey, the question and tip fields are presented for translation.

Thanks CasN for sharing your solution with the community!

== Create Question Pools==

''Tested with: ''

This workarounds was created by [http://www.limesurvey.org/component/option,com_comprofiler/task,userProfile/user,7511/lang,de/ user "akky"] and [http://www.limesurvey.org/component/option,com_fireboard/Itemid,105/func,view/id,18171/catid,11/limit,10/limitstart,10/lang,de/ posted in the forum]:

This is a simple solution to create question pools for Limesurvey. It will require access to the backend database. I'm not going to explain how to do this, as '''''if you don't understand it, then you shouldn't really do it'''''.

Basically 3 tables exist that we care about:
*lime_surveys - id field = sid
*lime_groups - id field = gid
*lime_questions id field = qid

In order to show the questions correctly the id field from the ''lime_groups ''table exists in the ''lime_questions ''table. This then is used to create the parent/child relationship.

However, if you want to create a pool of questions all you need to do is to amend the gid field in the ''lime_questions'' table to a value that doesn't exist in the ''lime_groups ''table. I would use 0 or a something silly like 10000. Try this with one question and you will notice it doesnt appear in the question list.

It's a crude workaround, but allows you to create as many questions as you want, without having them visible.

This could also be applied for groups as well just by using the sid field in the ''lime_groups ''table.

==Re-open a submitted answer==

''Tested with: 1.71+''

As an administrator you can re-open a submitted answer.
# Reset tokens invitation to not sent
# Reset answers to not completed
## '''release <= 1.72''': In LS <= 1.72 you don't have the option to "Reset answers to not completed" that version 1.8 offers, so this would require the following workaround:
### export of tokens
### vvexport of answers
### deactivate/activate survey in order to erase answers
### import answers from VVimport but Add the 'import as not finalized answers' option
### import tokens
## '''release >= 1.8''':
### from the answer summary page, a new option can be used to reset all answers to a not submitted state
### from the tokens summary page, you can reset all tokens to 'not sent' state

Note that this '''''will work only on non anonymous surveys with "Allow Persistence" option set'''''.

==Bypassing email check at registration==

When you allow public registration to your survey Limesurvey developers have opted to put in place a certain level of protection from bots and spammers by placing a captcha and by forcing the users to go and check their emails to find the link associated with their tokens.

Sometimes, however, this is a nuisance that actually force people to wait for the email when they would rather just take the survey and get on with things. Ideally it would be great if a token-based survey present the participant a short-text box (like a security question) asking at random one of the field in the registration form when the token is passed via URL (i will put this as feature request for the next edition!).

In the meantime, there is a very easy workaround. The solution is to edit the register.php and add the following code around line 156 (where the code is rewriting the page with the message that the email has been sent):

<a href='$publicurl/index.php?sid=$surveyid&token;=$newtoken&lang;=$baselang'>Whatever you want to say</a>

I placed right on line 156 between the two line breaks. The code is simply creating a link to the survey embedding the token in the URL.

NOTE that this is literally bypassing the safety currently in place, but the advantage is streamlining the steps for taking the survey with registration.

==Used email and public registration==

''Tested with v1.8''

When you have a closed survey with public registration, currently LimeSurvey is not allowing a user to re-use the same email. This is a problem if the user has deleted the registration email without taking the survey. In the above workaround a user was allowed to take a survey by presenting a link straight after the registration; ideally they should be prompted with an additional security question and/or captcha (see bugtracker). In the meantime, this owrkaround allows you to from a link from the corresponding email and present it to the user.

'''Make sure you back up your register.php first!'''

Here the querystring has been modified to pull out the token as well as the email address and the error message has been changed to display the link to the survey for the existing token. '''Please also note that this forced change will not be reflected in the different languages!'''

Around line 75 find the corresponding code:

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

//Check if this email already exists in token database

$query = "SELECT email,token FROM {$dbprefix}tokens_$surveyid\n"

. "WHERE email = ".db_quoteall(sanitize_email(returnglobal('register_email')));

$result = $connect->Execute($query) or safe_die ($query."<br />".$connect->ErrorMsg()); //Checked

if [[$result->RecordCount(]] > 0)

{

//transform in array of values

$row=$result->FetchRow();

$register_errormsg=$clang->gT("The email you used has already been registered.")."<br><br>".

"<a style='color:red;font-weight: bold;' href='$publicurl/index.php?sid=$surveyid&token;=".$row['token']."&lang;=$baselang'>Click this link to take the survey now</a><br><br>";

include "index.php";

exit;

}

</syntaxhighlight>

==HTTP-Refferer is not shown after a Redirect==

There are different ways to redirect a page, just as HTTP-Redirect 301, meta http-equiv="Refresh", meta http-equiv="Referrer", link rel=”canonical” or JavaScript window.location. But all of them don't work correct in all Browsers when it comes up to the HTTP-Referer. The only working solution I found is with a bit strange JavaScript. You see the solution at [http://www.visionen.ch/umfrage/redirect.pdf]

==Export graphic results to pdf==

Note: Limesurvey can export statistics with graphs to pdf from version 1.86.

Limesurvey is not yet able to export statistics to pdf. The following workaround is a solution to print your statistics (including graphs) to a pdf file with one page per question. You first will need to install a pdf printer (I use pdfcreator). Then you will need to modify Limesurvey as follows :
* open the common.php file
* after the line number 3615 (LS 1.80 build 6506) or 3641 (LS 1.80+ build 6601) or 3736 (LS 1.82+ build 6825) add the following line :

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

$strAdminHeader.="\t\t<link rel=\"stylesheet\" type=\"text/css\" href=\"styles/print.css\" media=\"print\" />\n";

</syntaxhighlight>
* create a new file named print.css in the admin/styles folder and write the following code in it :

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

@page {

size: 21.0cm 29.7cm;

margin: 1cm;

}

.statisticstable {

page-break-after:always;

}

</syntaxhighlight>
* visualize your stats with graphs from the admin panel then from your browser go to the file/print menu and select your pdf printer
* it prints your stats to a pdf file with one page per question