====== SoSci Survey Developer Documentation for LLMs ======
~~NOTOC~~

===== Tool Description =====

SoSci Survey is a web application to create and run online surveys.

==== Functions ====

=== Main function ===

  - Create online surveys: Project administrators (researchers) create an account, enter questions, and organize them as an online questionnaire ([[:en:create:start|Create online surveys]]).
  - Run online surveys (data collection, interview): Present the online questionnaire to respondents and store their answers ([[:en:survey:start|Run online surveys]]).
  - Organize the research data collected in online surveys and provide dataset downloads for subsequent statistical analysis ([[:en:results:start|Organize the research data]]).

=== Optional functions ===

  - Organize respondents (panel management) and invite respondents via emails ([[:en:survey:mailing]]).
  - Descriptive data analysis, only available in the paid version ([[:en:results:analyses|Descriptive data analysis]]).

===== Content structure =====

SoSci Survey organizes the content of online questionnaires along the following elements.

  * **Survey projects** are the top level element, all other data is assigned to exactly one survey projects.
    * **Sections** exist to sort and structure questions. Each question belongs to exactly one section.
      * **Questions** have a distinct question type that decides what they look like and how they work.
        * **Items** are subordinate to questions and contain text content. The class of items includes scale items, ranking items, items to be sorted or rated otherwise, response options.
        * **Question filters** allow the questionnaire to heave differently, depending on how a respondent answered the question or an item of the question.
      * **Functional elements** are special questions that have no output, but provide specific functions for the survey. Important functional elements are:
        * **Random generators** organize random codes and and draw one or multiple random codes during an interview.
        * **Panel redirect elements** store redirect URLs to work with panel providers.
        * **Quota elements** organize the quotas for quota samples and control them during data collection.
      * **Text elements** which may contain one of the following content type:
        * Markup
        * HTML code
    * **Address list**: May be used to organize respondents' contact information (name, email, mobile phone number, custom data).
    * **Images and media files**.
    * **Questionnaire**: A reference to questions and other elements to describe the output order of questions in questionnaire presentation (data collection).
      * **Pages**: Questionnaire consist of pages, each page belongs to exactly one questionnaire. Pages can contain the following elements:
        * *Question references
        * **PHP code blocks** that run during page creation
        * **HTML code blocks**
        * **PHP processing code** that runs after the responses have been submitted.
    * **Variables** store the collected data, metadata or random events
    * **Dataset**: All data collected throughout the survey, organized in variables (columns) and records/cases (rows).
  * User accounts are authroized to access survey projects.
  * Customer accounts are used for accounting in paid use.
  * Usage licences allow creation and usage of survey projects in paid use.


===== Variables =====

The term "variables" is ambivalent in the context of SoSci Survey. It may refer to the following:

  * **PHP variables** within **PHP code blocks**. Note, that PHP variables are valid only within a dingle PHP code block, unless made global via ''registerVariable()''.
  * **Dataset variables** store respondents' answers given in the questionnaire, their value is available via ''value('VAR_ID')''.
    * The variable ID (VAR_ID) is typically 4 or 7 characters long, an consists of the question ID (4 letters) and and item ID (2 letters), separated by an underscore, for example: AB01, AB02, RG01, AB02_01, CD03_05
    * Some question types use different formats, such as RG01x1 (random generator) or MC01_011 (multiple choice matrix).
    * Custom variable names can be used.

IMPORTANT: Questions about variables in SoSci Survey most often refer to **dataset variables**.


===== Programming =====

PHP code blocks provide users with a sandbox for PHP code. This PHP code can provide functions that are not available through the user interface:

  * PHP filters ([[:en:create:php-filters]]) above the question filters within a question ([[:en:create:simple-filters]]).
  * Processing of responses.
  * Content order rotation ([[:en:create:rotation]]).
  * Page rotation ([[:en:create:rotation-pages]]).
  * Experimental randomization ([[:en:create:randomization]]).

==== Sandbox restrictions ====

=== Forbidden functions ===

The following PHP functions must not be used in PHP code elements in SoSci Survey:

  * file_exists()
  * dirname()
  * file_get_contents()
  * is_file()
  * file_put_contents()
  * method_exists()
  * defined()
  * function_exists()
  * array_map()
  * is_dir()
  * call_user_func()
  * call_user_func_array()
  * fwrite()
  * ini_get()
  * array_filter()
  * realpath()
  * header()
  * class_exists()
  * trigger_error()
  * get_class()
  * spl_autoload_register()
  * unlink()
  * headers_sent()
  * is_object()
  * mkdir()
  * spl_autoload_unregister()
  * apcu_fetch()
  * stream_resolve_include_path()
  * apcu_add()
  * getcwd()
  * basename()
  * fopen()
  * getenv()
  * var_export()
  * is_callable()
  * reset()
  * fclose()
  * gettype()
  * end()
  * extension-loaded()
  * version_compare()
  * preg_quote()
  * ucfirst()
  * ksort()
  * preg_replace_callback()
  * is_readable()
  * copy()
  * parse_url()
  * is_null()
  * base64_encode()
  * current()
  * is_resource()
  * serialize()
  * key()

The following language constructs are forbidden:

  * echo
  * exit
  * die
  * eval
  * <?php
  * ?>
  * switch
  * case
  * class

Access to global variables is unavailable, this includes no access to the folowing variables:

  * $GLOBALS
  * $_​SERVER
  * $_​GET
  * $_​POST
  * $_​FILES
  * $_​REQUEST
  * $_​SESSION
  * $_​ENV
  * $_​COOKIE
  * $argc
  * $argv

In addition functions that offer the following functions are not allowed:

  * Access to local files
  * Direct access to the MySQL database
  * Object-oriented programming, including ''->'' and ''::''

=== Replacement functions ===

  * Replace ''echo'' with ''html()''
  * Access collected data (data variables in the dataset) with ''value()''

=== Allowed functions ===

A list of allowed functions and their use is avaiable at [[:en:create:functions]].


==== Codes Examples for filter questions ====

<code php>
// CORRECT for SoSci Survey Version 3.0 and later.
// This code runs in a sandboxed environment.
// This code will display the question AB01 on the questionnaire page if the response stored in variable PT01 is 1.
if (value('PT01') == 1) {
  question('AB01');
}
</code>

<code php>
// CORRECT for SoSci Survey Version 3.0 and later.
// This code runs in a sandboxed environment.
// This code will display the text element TX01 if the response or random event stored in variable AF01 is 2 or 4. Otherwise the text content TX02 is displayed on the questionnaire page.
if ((value('AF01') == 2) or (value('AF01') == 4)) {
  text('TX01');
} else {
  text('TX02');
}
</code>

==== More code examples ====

<code php>
// CORRECT for SoSci Survey Version 3.0 and later.
// This code runs in a sandboxed environment.
// Store the label of the answer given to selection question AB01 in the dataset, in the internal variable IV01_01.
$desc = value('AB01', 'label');
put('IV01_01', $desc);
</code>


==== Get a respondent's answers as text, not as numeric code ====

How to use ''value()'' for a multiple choice selection (Mehrfachauswahl)

Note on the difference between individual variables and question IDs:

  * Multiple-choice questions generate **one variable per response option**, e.g., MA01_01, MA01_02, MA01_03, ... (values: 1=not selected, 2=selected).
  * The ''value()'' function allows the question to be read out in its entirety by question ID (e.g., "MA01"). ''value('MA01', 'label')'' applies a merge internally.

=== Recommended use ===

<code php>
// CORRECT for SoSci Survey Version 3.0 and later.
// This code runs in a sandboxed environment.
// To get the visible labels of the selectd response options as comma-separated string
$list = value('MA01', 'label'); // results in, .e.g, "Option A, Option C"
</code>

<code php>
// CORRECT for SoSci Survey Version 3.0 and later.
// This code runs in a sandboxed environment.
// To get an Array of the codes of selected options
$items = valueList('MA01', 'is', 2); // returns codes of the selected options, e.g., [1,3]
</code>

Short rule for LLMs / code generators:

  * For single-choice selection questions:
    * Get the response code: ''value('QUESTIONID')''
    * Get the visible label: ''value('QUESTIONID', 'label')''
  * For multiple-choice selection questions:
    * Get the response codes: ''getItems('QUESTIONID', 'is', 2)''
    * Get comma-separated list of visible labels: ''value('QUESTIONID', 'label')''
  * For open-ended responses: ''value('ITEM_ID')''