LimeSurvey Manual - User contributions [en]

Report Writer

2012-04-17T15:19:49Z

Tacman1123:

When surveys are used for data collection, sometimes people have a need for very specific reports and they'd like integrated with the system. For example, an advocacy group doing a candidate questionnaire for someone running for political office may want to format the results in a way that can be published on their website. Or a health survey may want to print out advice that's specific to the responses.

== Template Engine==

For security reasons, I propose that the reports be written in a template engine, like Twig, is designed for rendering output. Allowing users to write PHP code is complex and potentially a huge security risk.

== Creating the Report==

I propose that the Report Editor have the same look and feel as the Template Editor, and possibly even use the same permissions, since templates and reports are in fact quite similar. Reports, in fact, can have their own templates that are independent from the website templates. From the main page, I propose adding an icon, in this graphic are example of three custom modules, one is Report Writer.

800

The Report Writer module has the template files, and by choosing a survey, the fields from that survey are also listed:

800

== Connecting Reports and Surveys==

Most reports will be specific to a survey, or more generally speaking, specific to data within a survey. So there needs to be a way to designate which surveys can be used with which reports. I envision a table of survey_id, report_id (and possibly some permission attributes), that could be done via a checkbox list within the survey configuration.

===Viewing the Reports Within Result Browsing===

Right now, there is an search icon that allows the administrator to view a survey response. Next to that icon, there could be a dropdown list of all the reports available, with <default> being the current report.

We could also allow multi-page reporting by letting admins check which responses they wanted to see and having the dropdown at the bottom, next to the red x (delete all responses).\

===Viewing A Report Within Individual Response===

On the page with the raw response (action=browse, subaction=id) we could have a dropdown or list of reports associated with this survey. Choosing one would allow the admin to see the data formatted in that report style.

Group Codes Proposal

2012-04-04T15:22:17Z

Tacman1123:

I'd like to propose that we add a group code (or "slug") to the group table, and that it be used when creating variable names an in the Expression Manager.

== The Problem==

Question groups are a great way to have survey building blocks, either for separate surveys or duplicating a block of questions. But since we now require unique question codes for each question, it's a lot of work to manage that. I propose that question codes be unique within groups, and group codes be unique within surveys.

Group codes could also be used in EM.

== The Database==

group_code (or slug) would be added to groups table, and make into a unique index (survey_id, group_code). During upgrade, we'd need a method to create a group code, either from the current group id (unique), the current order that the group is in with the survey (also unique, and a bit easier to understand) or the group name (checking for duplicates, etc.).

== How it Helps==

Suppose your survey has to do with children's names and ages. Right now, you'd create a group 'child1' with name and age questions, called child1_name, child1_age. For child 2, you export child1, import it as a new group, then change all the values one at a time. Then change all the conditions one at a time. Then do it again.

With a unique group code, you'd simply have 'name' and 'age' as qcodes, and a group_code of 'child1'. Internally this would map to 'child1_name'. Now when you import the 'child' group, you simply need to change one thing, the group_code, to child2. Now you have unique qcodes.

== Expression Manager==

Expression Manager would need to change to reflect that some expressions, especially conditions, are within-group only. For example, if you only want to ask the 'school' question if 'age' > 3, you'd need to indicate to EM that 'age' means "Age within this group". If you wanted a specific access, you'd need a format to say "child1.age", when you mean "the first one listed".

Group codes will also make import and exporting surveys easiers, and I'd like to see group_id dropped from everything except very low-level group edit functions.

Report Writer

2012-04-02T16:35:08Z

Tacman1123:

When surveys are used for data collection, sometimes people have a need for very specific reports and they'd like integrated with the system. For example, an advocacy group doing a candidate questionnaire for someone running for political office may want to format the results in a way that can be published on their website. Or a health survey may want to print out advice that's specific to the responses.

== Template Engine==

For security reasons, I propose that the reports be written in a template engine, like Twig, is designed for rendering output. Allowing users to write PHP code is complex and potentially a huge security risk.

== Creating the Report==

I propose that the Report Editor have the same look and feel as the Template Editor, and possibly even use the same permissions, since templates and reports are in fact quite similar. Reports, in fact, can have their own templates that are independent from the website templates.

== Connecting Reports and Surveys==

Most reports will be specific to a survey, or more generally speaking, specific to data within a survey. So there needs to be a way to designate which surveys can be used with which reports. I envision a table of survey_id, report_id (and possibly some permission attributes), that could be done via a checkbox list within the survey configuration.

===Viewing the Reports Within Result Browsing===

Right now, there is an search icon that allows the administrator to view a survey response. Next to that icon, there could be a dropdown list of all the reports available, with <default> being the current report.

We could also allow multi-page reporting by letting admins check which responses they wanted to see and having the dropdown at the bottom, next to the red x (delete all responses).\

===Viewing A Report Within Individual Response===

On the page with the raw response (action=browse, subaction=id) we could have a dropdown or list of reports associated with this survey. Choosing one would allow the admin to see the data formatted in that report style.

Database Storage Engine Project

2012-03-29T18:02:54Z

Tacman1123:

__TOC__

= Outline=

The project is focused around the Google Summer Of Code of 2010. Maarten [[(UserPage ttielu|ttielu]]) and Pieter-Jan [[(UserPage MrP|MrP]]) are the students assigned to the project.

The project is based on the DB Storage Engine proposal found at [[Project ideas for GSOC 2010]].

= Design and implementation=

A basic domain model of the problem can be found in [http://www.mediafire.com/?mytzjeggien this] pdf file.

This domain model can be used to build multiple databases. One would be to see the objects as tables. For the inheritance there would have to be some analysis to see how they should be mapped to the database. Here it would be important to use a low amount of joins. This structure has the disadvantage that when querying all information of a certain user, loads of joins might be required (depending on the complexity of the survey). On the other hand, queries about all answers on a single question can be very efficient. On top of that, tables are small.

Another example could be to remove the QuestionDependency and make one table per section. This would allow a more flat database structure, which reduces the number of joins necessary to retrieve all data from a single user. This could however create large tables and removes the possibility to loop over one question. This question will have to be placed into a new section and the loop will have to go over that section.

To allow these multiple database formats, we plan on using a [http://en.wikipedia.org/wiki/Factory_pattern factory pattern]. A DatabaseLayoutFactory can be used to choose the layout for a survey and in this way make it possible to add new database layouts for future use (for example a database which duplicates the data in both structures to get fast retrieval of both types of query).

Our plan would be to model the presented database models in detail and then implement at least one of them. Also we would want to model an API for the database (and of course implement that).

After creation of the survey, questions will be more or less static. To build upon this, it would be a good idea to store/cache the questions in a more static form, like a generated html-form, after creation of the survey.

== Database layouts==

=== Flat database===

A flat database would exist of a single table containing all answers to all questions.

Properties of this layout are:
* easy to export
* fast database operations
* hard to implement loops, branching & conditioning (introduce maximums on looping and have loads of NULL values OR use TEXT/BLOB fields containing sub structures => slow and unsearchable with quick operations)
* not suited for exotic question types (upload picture, matrix questions, multiple answer, multiple type questions, ...)
* database column limits might be hit
* best for simple surveys with huge amounts of answer data

=== Multitable database===

A multitable database would exist of multiple tables each containing the answers of a single question or questiontype.

Properties of this layout are:
* more difficult to export
* slower database operations (joins)
* supports all sorts of branching, conditioning, loops, ... including future features
* can support pictures, matrix questions, ... easily
* no problems with database column limits
* better for complex surveys with smaller amounts of replies

=== Hybrid database (section flat)===

The section flat model is a mix of the previous two models. In stead of mapping all answers in one table, we would map all answers to one section in one table. This allows the more advanced features (like looping, ...) to be handled between sections while still having a fast export of the different sections.

Properties of this layout are:
* easy to export
* fast database operations for simple surveys, operations for surveys with loads of loops, branching, ... will need joins (to handle the dependencies)
* database column limit only for really long sections (but they could be split in multiple sections, solving the problem)
* can support multiple question types (might result in using more columns, like in case of matrix questions)
* results in looping over sections instead of looping over questions in sections (hence if there is a loop over one question, there will be a section containing only this question; multiple questions in the same loop can be grouped in one section)

=== Layout mock-ups===

Mock-ups for the database layouts can be found in [http://www.mediafire.com/?nwjwy2c34mw this] pdf file.

The survey used is:

1) how many children do you have? '''int'''

loop: amount of children {

2.1) give the name of you i'th child '''string'''

2.2) what is the age of your i'th child '''int'''

}

3) What kind of ice cream do you like? (multiple choice)

3.1) I don't like ice cream

3.2) vanilla

3.3) strawberry

3.4) chocolate

3.5) other: 3e) '''string'''

4) what do you eat? (multiple answer: checkboxes)

4.1) candy

4.2) cookies

4.3) fruit

= Action Plan=

(To be specified more in detail later)

== Outline==

Main deliverables:
*Database design for flat database
*Database design for multitable database
*Database design for section-flat database
*Class diagram for the database system
*API and documentation with the database system - keep support for metadata in mind.
*Implementation of the database system with at least one database layout (more if spare time is found)

== Milestones==

The first series of milestones is slightly smaller since both Maarten and Pieter-Jan have exams in the month of June.

{|
|Milestone||Deadline
|-
|[[Database Storage Engine Project M1 Database Design||Database designs]]||26th of June
|-
|[[Database Storage Engine Project M2 API||API]]||30th of June
|-
|[[Database Storage Engine Project M3 Class diagram||Class diagram]]||7th of July
|-
|[[Database Storage Engine Project M4 Basic implementation||Implement basic classes]]||14th of July
|}

The second series of milestones contains the biggest part of the implementation and testing.

{|
|Milestone||Deadline
|-
|Test Prototype||31st of July
|-
|Finish and test Section Flat plugin||4th of August
|-
|Implement and test question types||9th of August
|-
|Test and debug the global project||16th of August
|}

= Meeting log=

The meeting log can be found here: [[Database Storage Engine Project Meeting Log]]

Theme editor

2012-02-01T11:43:23Z

Tacman1123:

{maketoc title="Contents:"}

=Introduction=

LimeSurvey has a basic template and style system providing a theme-like capability found in many browser-based applications. They are simply termed '''Templates''' here. The Templates allow control over the look and feel of pages during a survey. A survey administrator can select the template to use for each survey to thus personalize that survey's look and feel. Changes to a Template can be as simple as adding a unique logo on the welcome page, changing background colors, or maybe new text colors for specific types of questions.

LimeSurvey comes with a set of templates right out of the box. These initial templates are defined by directories within the LimeSurvey installation "templates" directory. Each template has it's own directory. Within the main directory of a template are numerous files: '''templates (.pstpl)''', '''cascading style sheets (.css)''', '''images''' ('''.jpg''' or '''.png''') and maybe others.

Like in other theme-based systems, fragments of HTML code are stored in the .pstpl template files. These fragments are read in and used to construct the page to display to the end user during the operation of a survey. Often '''keywords''' surrounded by curly braces are included in the files that are then replaced with the relevant text. The following gives an example of a template file content and its result when used in a survey page:

<syntaxhighlight lang="php" enclose="div"><center>{SURVEYNAME} 

{SURVEYDESCRIPTION}</center></syntaxhighlight>

One gets a result that looks like:

<div class="simplebox"><center>'''My New Survey'''</center>

<center>This is a survey written by me to find out what sort of chocolate people like.</center></div>

Templates, being HTML code, tend to define the positioning and type of text to be displayed and similar structural features of the page. They often reference or include other files. Most reference a common cascading style sheets (CSS) file that defines the font style, color, size, background and similar parameters common to all pages in the survey. Style sheets reference HTML '''class''' parameters that are associated with the various types of objects in the HTML code. This allows the style sheet to describe once how to display each of the many types of text or other objects that may appear in multiple places. There are unique classes for each question type in LimeSurvey and thus giving detailed control over the appearance of each. Image files, like logos or special progress-bar constructors, may be referenced as well in the Template file. Finally, special Keywords in curly braces are replaced with text defined in the Survey for each of its corresponding language translations (for example, the Survey Title or Question Text for each language defined).

If you create a new custom template, please consider contributing it back to the LimeSurvey community, and make it available to others. With your help, we can grow our repository of templates, surveys, and other ad-ons, to make LimeSurvey even better! See the shared [http://www.limesurvey.org/component/remository/lang,en-gb/ Template Repository]

=Creating a new Template=

To be able to create a new template (or edit an existing template), you need Template Editing user permission in LimeSurvey as well as permission to manipulate the files in the underlying operating system hosting your LimeSurvey installation.

<div class="simplebox">'''Note of Warning:''' As template changes can affect all surveys in an installation, changes should be limited to those skilled in understanding general concepts in the code base. Templates are an advanced feature that can take some experimentation to get correct if you are not familiar with HTML code methods.</div>

The preferred way to create a new template is through the Template Editor (see below) via the web Admin interface. Some people may like to work directly with template files so that they can use their favorite text editor instead of the web interface. In this case, still use the Template Editor to first create your new template. This will create a new base template with all the files you need in the LimeSurvey_web_root/upload/templates/your_new_template directory. From there you can use your text editor to manually adjust the template files.

<div class="simplebox">'''Permissions Note:''' on unix/linux systems, these template files will be owned by the group and user who the web server is running as (may be "www" for some systems). So make sure you have access to edit these files, and when you save them make sure they don't change ownership, so you can still use the web Template Editing interface if needed</div>

Template files may seem complex to understand at first. You have to likely understand HTML code, possibly Styles and Style Sheets, and have access to the underlying LimeSurvey installation files if the template files and directories are not editable. Copy an existing template to a new directory to play around with the content. This may help make the concept clearer.

A number of the 'public' elements of LimeSurvey can be adjusted by a series of templates. This section provides a very brief explanation of these templates, however more detailed information - especially regarding the editing/creation of new templates is available under [[Templates + Styles]].

=The LimeSurvey Template Editor=

To ease the understanding and quick update of a Template, LimeSurvey provides a '''Template Editor''' in the main '''administrative''' toolbar of the application. This Template Editor is only available to users given the privilege in the User Security settings. A template effects all surveys and can render a survey inoperable if not constructed properly. So Template editing is thought best restricted to a very limited, knowledgeable set of users. Having permission to enter the Template Editor is not enough though.

The LimeSurvey Template Editor allows you to edit the contents of your templates online. Start the Template Editor by clicking on the "Template Editor" icon [[File:templates.png]] in the LimeSurvey Administration toolbar (Templates). The main screen is similar to the LimeSurvey Survey Administration screen. It allows you to select the template to edit/view. Once this has been selected you can then select from one of the different public survey pages. You are then presented with a list of the template files that make up that particular page.

==The Template Menu==
*'''Edit Icon:''' The "edit" icon indicates whether or not the template is editable. A blurred out icon indicates that the template is read only; a clickable icon indicates you may make modifications. To change the icon from blurred to clear, you have to modify the template's permissions.
*'''Rename this template:''' Allows you to change the name of the template. Generally used after copying an existing template or importing a template by manipulating the underlying directories.
*'''Export Template:''' Allows you to export the current template to a .zip-File.
*'''Copy Template:''' Allows you to make a new template by copying the current one.

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

==Import/Export/Copy a Template==

When you '''export '''a template, this will create a zip-file archive with all the files your template consists of (.pstpl files, images, css files, ...). You can simply '''import '''the exported zip-file at other Limesurvey systems by using the import feature or you can manually copy the archive to another installation and extract it into the corresponding template directory there. If you copy the template in the same installation, you will need to rename the folder to create another named copy of that template.

If the file and directory permissions are open for the LimeSurvey application to write, then you can use the programs '''copy '''and rename features to make a local copy of a template.

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

==Template Files==

The following template files are used to produce your public survey and must exist in any new template folder you create:
*'''startpage.pstpl:''' Produces the start of each html page. It starts at the "<head>" tag, and should not contain the "<html>" tag. This 'very beginning' of a standard html page is written by the scripts. Please ensure that your startpage.pstpl files contains a <body> tag, even though many browsers do not require strict adherence to the W3 HTML stanards, the LimeSurvey script needs to find a <body> tag, to run certain javascript elements. It is not expected that many 'keywords' will be used in the startpage.pstpl file, however you may wish to put the {SURVEYNAME} into the title. The startpage.pstpl file can contain code that ends in the corresponding endpage.pstpl file, so you can start a table in this file and close the table in the endpage.pstpl file. The startpage.pstpl and endpage.pstpl files wrap around every possible page used by LimeSurvey.
*'''survey.pstpl:''' This template is the second used on most pages, and provides a space to put the survey name and description. This template does not have a corresponding 'closing' template, and subsequently you should close all tags opened in this template file (ie: don't leave a table open here because there is nowhere else to close it)
*'''welcome.pstpl:''' This template is only used in the welcome screen (which is also on the main page for 'all in one' surveys). You can use this to print out the welcome text, and other information that should be provided in the introduction. Like the 'survey.pstpl' file, there is no corresponding 'closing' template, so all tags opened in this template file should be closed as well.
*'''startgroup.pstpl:''' This template can provide a 'summary' wrap around for questions within a group. It has a matching 'endgroup.pstpl' template that can be used to close any opened tags in this file, so you can open a table within this.
*'''groupdescription.pstpl:''' This template file is used to display a description of a group. It is separate to the startgroup.pstpl file because in a "question by question" survey it will be displayed on its own unique page in between groups, whereas in a "group by group" or "all in one" survey it provides a header to the subsequent questions. groupdescription.pstpl does not have a corresponding 'closing' template file, so all tags should be closed.
*'''question.pstpl:''' This file contains the question, answer and help text sections of your survey, and in the "group by group" and "all in one" surveys this template is cycled repeatedly with each question. There is no corresponding closing file for this and all tags should be closed.
*'''question_start.pstpl:''' This file contains the individual elements found at the start of a question. It is included within 'question.pstpl' via the {QUESTION} keyword. It is intended to allow template designers more control over the layout of a question. This template sits outside the normal templating system and '''was superseeded (as of LS1.87)'''. All keywords from this template are now available directly in question.pstpl. NOTE: templates using question_start.pstpl will still work at least for a couple more versions of LS 1.x
*'''submit.pstpl (and privacy.pstpl):''' This page is the penultimate page for all types of survey (except the "all in one" type) where the participant is given an option to review questions before submitting their responses. It provides privacy information where a survey is anonymous, which it extracts from the '''privacy.pstpl''' file.
*'''completed.pstpl:''' This page is displayed as the final page when the survey responses have been saved and the survey is over. It can be used to display a "forwarding link" as set in the survey setup.
*'''endgroup.pstpl:''' This file closes the group, and can be used to close off any tags opened in the startgroup.pstpl file
*'''navigator.pstpl:''' This file contains the buttons that navigate through the survey, "next", "prev", "last", "submit", "save so far" and the "clear all" link. It is used in all pages except the completed page.
*'''printanswers.pstpl:''' This file has the HTML wrapper for the print version of the survey.
*'''print_group.pstpl:''' This file is the same as startgroup.pstpl endgroup.pstpl but for the print version of the survey.
*'''print_question.pstpl:''' This file is the same as question.pstpl but for the print version of the survey.
*'''print_survey.pstpl:''' This file is the same as survey.pstpl but for the print version of the survey.

==Other Template Files==

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

==Standard Pages==

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

{|
| '''Survey Pages:''' '''Template Files'''||Survey List||Welcome||Question||Completed||Clear All||Register||Load||Save||Print Answers||Print Survey
|-
|SurveyList|| [[File:check.gif]]|| || || || || || || || ||
|-
|Welcome|| || [[File:check.gif]]|| || || || || || || ||
|-
|Privacy|| || [[File:check.gif]]|| || || || || || || ||
|-
|Navigator|| || [[File:check.gif]]|| [[File:check.gif]]|| || || || || || ||
|-
|Survey|| || || [[File:check.gif]]|| || || [[File:check.gif]]|| || || ||
|-
|StartGroup|| || || [[File:check.gif]]|| || || || || || ||
|-
|GroupDescription|| || || [[File:check.gif]]|| || || || || || ||
|-
|Question'''*'''|| || || [[File:check.gif]]|| || || || || || ||
|-
|EndGroup|| || || [[File:check.gif]]|| || || || || || ||
|-
|Assessment|| || || || [[File:check.gif]]|| || || || || ||
|-
|Completed|| || || || [[File:check.gif]]|| || || || || ||
|-
|ClearAll|| || || || || [[File:check.gif]]|| || || || ||
|-
|Register|| || || || || || [[File:check.gif]]|| || || ||
|-
|Load|| || || || || || || [[File:check.gif]]|| || ||
|-
|Save|| || || || || || || || [[File:check.gif]]|| ||
|-
|PrintAnswers|| || || || || || || || || [[File:check.gif]]||
|-
|Print Survey || || || || || || || || || || [[File:check.gif]]
|-
|Print Group || || || || || || || || || || [[File:check.gif]]
|-
|Print Question || || || || || || || || || || [[File:check.gif]]
|-
|StartPage EndPage Template.css|| [[File:check.gif]]|| [[File:check.gif]]|| [[File:check.gif]]|| [[File:check.gif]]|| [[File:check.gif]]|| [[File:check.gif]]|| [[File:check.gif]]|| [[File:check.gif]]|| [[File:check.gif]]||
|}

'''*'''NOTE: In versions 1.90 and up this replaces question.pstpl AND question_start.pstpl. If you are using an old custom template, you need to add the following line to the beginning of question.pstpl:<syntaxhighlight lang="php" enclose="div"><div {QUESTION_ESSENTIALS} class="{QUESTION_CLASS}{QUESTION_MAN_CLASS}{QUESTION_INPUT_ERROR_CLASS}"></syntaxhighlight>And then add the corresponding closing tag to the end of question.pstpl:<syntaxhighlight lang="php" enclose="div"></div></syntaxhighlight>

==The File Control Section==

In the "file control" window on the left, you can click on one of the template files that is used to compile the page. The HTML code for that file will then appear in the "Now editing" window in the center. If the template is editable (determined by directory permissions) you can then make any changes and save them.

The "Other Files" window shows a list of all other files in the template directory. You can use the right side to '''upload and select image files (your pics, logos,...) or other files needed to create your template'''. Note: Instead of a link directly to each picture in your template you can use the field string {TEMPLATEURL}. So instead of:

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

<syntaxhighlight lang="php" enclose="div">img src='{TEMPLATEURL}mypicture.jpg'</syntaxhighlight>

A "sample" of the template page you are editing will be visible at the bottom of the screen. There is no way to to delete a template from the template editor. This must be done by accessing the underlying directory and deleting the file there.

<div class="simplebox">'''Note:''' The shipped templates cannot be edited using the Template Editor and should never be changed. If you want to modify them, create a copy first and modify the copy.</div>

==Location of template files==

LimeSurvey stores each of the 'standard' templates in their own distinct sub-directory within the /templates directory that is kept in the public directory with the other LimeSurvey public files. Customized user templates are stored in the /upload/templates directory.

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

There should ALWAYS be a "default" directory in the templates directory. This template is used by default and as a fall-back if a template folder doesn't exist, or can't be found. The "default" directory comes with the package.

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

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

=Styling questions with CSS=

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

<syntaxhighlight lang="php" enclose="div"><div id="question5" class="gender">

...

</div></syntaxhighlight>

and if the question is mandatory

<syntaxhighlight lang="php" enclose="div"><div id="question5" class="gender mandatory">

...

</div></syntaxhighlight>

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

<syntaxhighlight lang="php" enclose="div"><div id="question5" class="gender mandatory input_error">

...

</div></syntaxhighlight>

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

<syntaxhighlight lang="php" enclose="div"><div id="question6" class="text-short input_error">

...

</div></syntaxhighlight>

==The full list of question classes==

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

==Importing styles into your custom template==

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

START: Question styles <strike>-</strike><strike>-</strike><strike>-</strike><strike>-</strike><strike>-</strike> */</syntaxhighlight>

If you're styling your own custom template, You should be able to copy everything after the above from templates/default/template.css (for tables based layouts) or /templates/limespired/template.css (for CSS based layouts) into your own style sheet without any impact on your other styles.

==Internet Explorer conditional style sheets==

Because of the marked discrepancies in rendering between IE6, IE7 and most other browsers, there are special IE conditional style sheets included for each template.

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

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

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

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

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

==Keywords==

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

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

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

==Input/Buttons==

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

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

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

Because you can edit all the HTML aspects, there's no reason to surround your templates with a <div class='new_name'> and then define a css for that new_name class.

==Styling the progress bar==

'''Before version 1.87:'''

The chart.jpg file is a simple one pixel image file which is used to create the progress bar image in the 'PERCENTCOMPLETE' table. If the file does not exist, LimeSurvey will use the default 'maroon' coloured image in the public directory. If you want to create a bar to match your own colour scheme, then you should save the color in this file. Remember it should be a '''JPEG''' file, 1 pixel x 1 pixel, in the colour desired.

'''Version 1.87 and newer:'''

The progress bar appearance can be modified with CSS.

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

<syntaxhighlight lang="php" enclose="div">#progress-wrapper .ui-widget-header {

background-color: #3300FF;

}</syntaxhighlight>

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

<syntaxhighlight lang="php" enclose="div">#progress-wrapper .ui-widget-content,
#progress-wrapper .ui-widget-header {

border: 1px solid #FF0000;

}</syntaxhighlight>

==Advanced Features Available to Developers==

Starting with version 0.99, LimeSurvey has integrated some user-made patches that allow for some special changes. These very advanced features generally require changes to the underlying code base of LimeSurvey and should be done carefully so as not to introduce security holes.

===Basic CMS Integration support===

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

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

<nowiki>

$embedded = false;

$embedded_inc = ""; // path to the header to include if any

$embedded_headerfunc = ""; // e.g. COM_siteHeader for geeklog

$embedded_footerfunc = ""; // e.g. COM_siteFooter for geeklog

</nowiki>

Set '''$embedded = true;''' to enable CMS-embedding. By using the '''$embedded_inc''' variable one can include their own '''.php''' files. By setting '''$embedded_headerfunc''' or '''$embedded_footerfunc''', one can call functions from within included files that output the relevant headers or footers instead of LimeSurveys default ones.

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

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

'''Version 1.87 and newer:'''
*Disable XSS filter - in Global settings -> Security, set "Filter HTML for XSS" to No.
*Enter your script in the source of a question or group description.
*There are more details in the [http://docs.limesurvey.org/tiki-index.php?page=Workarounds%3A+Manipulating+a+survey+at+runtime+using+Javascript&structure;=English+Instructions+for+LimeSurvey#How_to_use_Script_eg._JavaScript_etc._in_LimeSurvey_ workaround section].

=Videos on Templates=

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

Part I

{YOUTUBE(movie="nLsfxMjRXyk?fs=1&hl=en_US&rel=0",width="640",height="385")}{YOUTUBE}

Part II

{YOUTUBE(movie="yrAXStFH34Q?fs=1&hl=en_US&rel=0",width="640",height="385")}{YOUTUBE}

Part III

{YOUTUBE(movie="TYlJXHgt8R0?fs=1&hl=en_US&rel=0",width="640",height="385")}{YOUTUBE}

Part IV

{YOUTUBE(movie="Rml0gqeErVc?fs=1&hl=en_US&rel=0",width="640",height="385")}{YOUTUBE}

Part V

{YOUTUBE(movie="LX24Ix1ylmY?fs=1&hl=en_US&rel=0",width="640",height="385")}{YOUTUBE}

Part VI

{YOUTUBE(movie="-202CqQcW8g?fs=1&hl=en_US&rel=0",width="640",height="385")}{YOUTUBE}

=Tips & Tricks=

==Some language specific element==

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

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

<syntaxhighlight lang="php" enclose="div"><div class="fr" lang="fr">Pour de l'aide en direct appelez le 000000</div>

<div class="en" lang="en">For some help, please call 000000</div></syntaxhighlight>

ans in template.css

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

.lang-en .fr{display:none}</syntaxhighlight>

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

==Change the layout of the survey page==

When editing a template this template can be assigned to a single survey while the survey list page, which is shown at www.yourdomain.org/limesurveyinstallfolder, lists all your surveys.

To use your current template for this page you have change the according setting at the Global Settings screen; at older versions this change can be done by editing the $defaulttemplate setting at the config file: Copy this setting from config-defaults.php to config.php which overrides config-defaults.php and edit this setting to $defaulttemplate = 'yourtemplatename';

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

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

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

$ unzip template.zip -d template

Archive: template.zip

inflating: template/startpage

inflating: ...

or scripts in their mac-compiled counterparts:

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

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

If you haven't already, set the admin directory to read/write/execute (777). The files within it, however, may be set to read/execute only (chmod 755).

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

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

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

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

==Replacing the help icon==

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

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

==Replacing an existing logo==

'''Note''': Before uploading new logo delete previous one.

1. To edit logo go to &bdquo;template.css”, you can find it here (see in screen):

[[File:1.PNG]]

2. Find and Click Search button, to find place where is logo style text.

[[File:2.PNG]]

3. Find in search #logo (It is logo design code)

[[File:3.PNG]]

4. Edit style file

You will see something like this code:

[[File:4.PNG]]

If you want change image just replace logo.gif to antoher image link. Like: (logo.png, logo.jpg, logo.swf).

If you want change image size just change, width and height (in pixels) like:

<syntaxhighlight lang="php" enclose="div">Width:100px; Height:100px;</syntaxhighlight>

==Adding your own logo==

1. Find and Open &bdquo;startpage.pstpl” template file.

[[File:5.PNG]]

2. Write in &bdquo;startpage.pstpl” this line:

<syntaxhighlight lang="php" enclose="div"><img id=”page_logo” src=”{TEMPLATEURL}logo.png”> </syntaxhighlight> After <syntaxhighlight lang="php" enclose="div"><body ... ></syntaxhighlight> tag

[[File:6.PNG]]

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

[[File:1.PNG]]

3.1 Go to end of &bdquo;template.css” style file.

3.2 Write in end:

'''If you want in left side:'''

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

float:left;

}</syntaxhighlight>

'''If you want in right side:'''

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

float:right;

}</syntaxhighlight>

'''If you want in center:'''

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

display: block;

margin-left: auto;

margin-right: auto;

}</syntaxhighlight>

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

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

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

== Display custom favicon==

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

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

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

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

(''Version 1.91 and newer'')

If you want LimeSurvey to change the appearance of every second page (i.e. of even and odd survey pages) you can use '''.page-odd''' class in your css file to change the appearance of odd pages.

example from default template of LimeSurvey 1.91+

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

.page-odd table.question-group {

background-color: #D2F2D3;

}</syntaxhighlight>

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

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

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

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

table.question thead td.header_separator,

table.question tbody td.dual_scale_separator

{

border-right:solid 1px #00A8E1;

}

</syntaxhighlight>

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

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

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

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

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

</syntaxhighlight>

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

If you want to remove the survey contact message from error messages it'll be trickier. You can add the following function call to the '''$(document).ready''' function in the '''template.css''' of your used design template:

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

removeContactAdressFromMessage(); //Removes the survey contact message from error messages

</syntaxhighlight>

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

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

function removeContactAdressFromMessage()

{

if ($('#tokenmessage').length > 0)

{

var oldMessage = $('#tokenmessage').html();

var indexContact = oldMessage.indexOf('Bitte kontaktieren');

var newMessage = oldMessage.substr(0, indexContact);

$('#tokenmessage').html(newMessage);

}

}

</syntaxhighlight>

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

RemoteControl

2011-01-15T17:25:10Z

Tacman1123:

__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' 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 .= " SOAP Error: ".$fault->faultcode." : ".$fault->faultstring;

}

</syntaxhighlight>

The LSRC offers some functions:

(m) means: Mandatory Parameter

==sCreateSurvey==

Parameters changed after 1.81+! (sVend added)
* 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''':
*** (m) string USER, this have to be an existing Useraccount with appropriate rights
*** (m) string PASSWORD, this has to match the password for the account.
*** (m) int $iVid, SurveyID desired ID for the Survey, make sure it doesn't already exist in LimeSurvey
*** (m) string $sVtit, SurveyTitle, should be the (Nr +)Name of the Event to be evaluated
*** (m) 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''':
*** (m) string USER, this have to be an existing Useraccount with appropriate rights
*** (m) string PASSWORD, this has to match the password for the account.
*** (m) 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''':
*** (m) string USER, this have to be an existing Useraccount with appropriate rights
*** (m) string PASSWORD, this has to match the password for the account.
*** (m) int SurveyID, the SurveyID
*** (m) 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''':
*** (m) string USER, this have to be an existing Useraccount with appropriate rights
*** (m) string PASSWORD, this has to match the password for the account.
*** (m) int SurveyID, the SurveyID
*** (m) 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''':
*** (m) string USER, this have to be an existing Useraccount with appropriate rights
*** (m) string PASSWORD, this has to match the password for the account.
*** (m) 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''':
*** (m) string USER, this have to be an existing Useraccount with appropriate rights
*** (m) string PASSWORD, this has to match the password for the account.
*** (m) 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''':
*** (m) string USER, this have to be an existing Useraccount with appropriate rights
*** (m) 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''':
*** (m) string USER, this have to be an existing Useraccount with appropriate rights
*** (m) string PASSWORD, this has to match the password for the account.
*** (m) int surveyID, Id of the survey from which participants will be mailed
*** (m) 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''':
*** (m) 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.
*** (m) string USER, this have to be an existing Admin-, Superadmin- or Useraccount with the rights to create and activate Surveys
*** (m) 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''':
*** (m) 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.
*** (m) string USER, this have to be an existing Admin-, Superadmin- or Useraccount with the rights to create and activate Surveys
*** (m) 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''':
*** (m) int SurveyID, the ID for the Survey from which you want get the unused tokens
*** (m) string USER, this have to be an existing Admin-, Superadmin- or Useraccount with the rights to create and activate Surveys
*** (m) 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''':
*** (m) int SurveyID, the ID for the Survey from which you want to get the Fieldmap.
*** (m) string USER, this have to be an existing Admin-, Superadmin- or Useraccount with the rights to create and activate Surveys
*** (m) 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==

''(since 1.86)''
* '''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/remotecontrol/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.