====== put() ======

''void **put**(string //variable//, mixed //value//, [boolean //EachVariable//])''

The function ''put'' enables you to store a single value in the data record. ''put()'' is used when the questionnaire calculates or draws a value -- and this value is needed for the analysis. For example, if the stimulus in a question is varied at random, then which one the respondent made a statement on has to be known for the analysis.

  * //variable//\\ The ID of the internal variable (see below), in which the //value// should be saved. The ID is entered as a string in quotation marks, e.g. '''IV01_01'''.
  * //value//\\ A number or text (string), which should be stored in the variable. Ordinarily, a variable with the corresponding value is given as the second parameter.
  * //EachVariable// (optional)\\ Normally, ''put()'' only stores in [[en:create:questions:internal|internal variables]]. In some cases it may be useful to overwrite the value of another variable. In this case a third parameter ''true'' can be specified.

**Warning:** Only use the third parameter //EachVariable// if you know exactly what you are doing and an internal variable cannot be used. Changing response codes can invalidate the validity of the data set. For most cases the functions ''[[:en:create:functions:preset]]'' and ''[[:en:create:functions:dropvalue]]'' are much better suited.

**Tip:** If you want to save not a single value but a whole array in the data set, use ''[[putlist]]''.



===== Internal Variables =====

Before ''put()''  can be used, create an internal variable in the data record. In order to do this, create a new question in the **List of Questions** with the type [[:en:create:questions:internal|internal variables]], with at least one variable (item) in it. The complete ID for this variable is entered as the first parameter in the command ''put()''. The ID can be found in the **Variables Overview** (e.g. if it is the first variable in the first question in the "IV" category, the ID is "IV01_01").


**Tip:** Items in a question with the type "internal variables" can also be used in order to save values from JavaScript. To do so, integrate the question in the same way as usual, and write the responses in the hidden input fields that are generated ([[:en:create:inputs-custom|Use Custom Form Elements]]).




===== Calculations =====

The following example assumes that one construct is assessed in two scales with the question IDs AB01 and AB02 -- and that an internal variable AB03_01 was created in order to save the [[:en:general:indices|scale index]] (total value of all items).

<code php>
$sum01 = valueSum('AB01');
$sum02 = valueSum('AB02');
$index = $sum01 + $sum02;
put('AB03_01', $index);
</code>

Determining the scale index during the survey is particularly useful if you want to inform the participant of the result, or if it is required for a filter:


<code php>
if (value('AB03_01') > 100) {
  question('FU03');  // question for people who rate the construct higher on the scale
} elseif (value('AB03_01') > 50) { {
  question('FU02');  // question for people who rate the construct averagely on the scale
} else {
  question('FU01');  // question for people who rate the construct lower on the scale
}
</code>


===== Recode Answers =====

Recoding values is typically done in the data analysis, but if you already need the recoded values in the interview (e.g. in a [[:en:create:php-filters]]), you can also do this directly in SoSci Survey.

For example, if you want to recode the open-ended text input for age from the variable "SD02_01" into the categories <25 (1), 25-40 (2) and 40+ (3), you would use the following PHP code on the page after the age question.

<code php>
$age = (int)value('SD02_01');
if ($age < 0) {
  put('IV01_01', -1);  // Errorcode for invalid responses
} elseif ($age < 25) {
  put('IV01_01', 1); 
} elseif ($age <= 40) {
  put('IV01_01', 2); 
} else {
  put('IV01_01', 3); 
}
</code>

The ''(int)'' converts the open input into an integer. The internal variable "IV01_01" in the example must be created beforehand in the list of questions.


===== Transforming Codes =====

SoSci Survey stores positive response codes for scales ([[:en:results:values]]). If you need the value range from -2 to +2 for a five-level scale in the data set, you can recode individual variables as follows.

**Note:** In practice, the recoding or transformation of values is usually part of the evaluation and is therefore performed in the statistics software. There are therefore only very special cases in which such a transformation makes sense already during the survey.

**Note:** To "rotate" individual items of a scale (e.g. to save a 5 instead of a 1 for "does not apply", as with the other items), select the item on the left in the **Question Catalogue** and activate the option //Invert answer codes for this item//.

The following code transforms the answers for the scale item SK01_01 from the value range 1 to 5 into the range -2 to +2. If no valid answer was given for the scale item (item omitted or an alternative option selected), no value is stored in the data set. The PHP code is placed on the page after question SK01 (see notes on ''[[:en:create:functions:value]]'').

Precondition is that an internal variable SK02_01 has been created in advance (see [[#internal_variables|above]]).

<code php>
$original = value('SK01_01');
// Save only valid values (>0)
if ($original > 0) {
  put('SK02_01', $original - 3);
} else {
  put('SK02_01', false);
}
</code>

The PHP code can also be made shorter (but less clear):

<code php>
$org = value('SK01_01');
put('SK02_01', ($org > 0) ? $org - 3 : false);
</code>

If this transformation is to be performed for all items of the scale SK01 (and sufficient internal variables have been created in SK02), the following [[:en:create:filter-itemcount#loops|loop]] does this task. The "inner" part of the PHP code is almost identical to the PHP code above. The function ''[[:en:create:functions:id|id()]]'' only creates the IDs SK01_01 to SK01_10 (for e.g. 10 items).

<code php>
$items = getItems('SK01');
foreach ($items as $item) {
  $original = value(id('SK01', $item));
  if ($original > 0) {
    put(id('SK02', $item), $original - 3);
  } else {
    put(id('SK02', $item), false);
  }
}
</code>


===== Advanced Filter =====

The following example is taken from a questionnaire that shows different questions at several points for new customers and existing customers. A new customer distinguishes himself by showing that he is yet to have bought anything (answer 1 in selection question "KD01") __and__ that the current order has not yet been delivered (answer 1 to 3 in selection question "KD02"). 

Of course, the [[:en:create:filters|filter]] could be repeated on each page with different questions -- on the one hand, however, this is unnecessarily complicated, and, on the other hand, the distinction between new and existing customers is needed in the analysis anyway. Therefore, the this should be saved in the internal variable "KD03_01".

<code php>
if ((value('KD01') == 1) and (value('KD02') <= 3)) {
  put('KD03_01', 1);  // code 1 for new customers
} else {
  put('KD03_01', 2);  //code 2 for existing customers
}
</code>

The saved code can be used on later pages for filters with no hassle.

<code php>
if (value('KD03_01') == 1) {
  question('SU02', '1-3,5');  // in question SU02 show items 1, 2, 3 and 5
} else {
  question('SU02', '1,2,5-7');  // in question SU02 show items 1, 2 and 5, 6, 7 
}
</code>

===== Randomization I =====

If you use ''shuffle()'' to create a randomly mixed list, it will not be saved at first. With ''put()'' you can either save the mixed list -- or the ranking of the elements. Depending on what is needed for the evaluation.

The following PHP code randomly arranges the values from 1 to 10:

<code php>
$elements = array(1,2,3,4,5,6,7,8,9,10);
shuffle($elements);
</code>

The content of the mixed array ''$values'' could look like this:

^Index^0^1^2^3^4^5^6^7^8^9^
|Element|7|2|10|5|9|4|8|3|6|1|

Die zugehörigen Ränge wäre dann:

^Element^1^2^3^4^5^6^7^8^9^10^
|Rang|10|2|8|6|4|9|1|7|5|3|

To save the sequence, you need a question of the type "internal variables" with the same number of variables (items) as the list has elements, e.g. for this example 10. If the question has the ID ''IV01'', the values can be saved in the data set in the mixed sequence as follows:

<code php>
for ($i=0; $i<count($elements); $i++) {
  // Create internal variable ID from question ID plus index
  $id = id('IV01', $i + 1);
  // Save the value from the array here
  put($id, $elements[$i]);
}
</code>

To the index ''$i'' the value one is added in the line with ''[[:en:create:functions:id]]'', because the indices of arrays start counting at 0, but the internal variables start counting at 1.

Often it is more useful to save the ranks of the elements. For example if ''shuffle()'' is used to mix texts, images or pages in the questionnaire randomly. You can save the ranks of the elements with the following PHP code.

<code php>
for ($i=0; $i<count($elements); $i++) {
  // Create internal variable ID from question ID plus element content (!)
  $id = id('IV01', $elements[$i]);
  // Save the rank here
  put($id, $i + 1);
}
</code>

Of course, this code only works if the elements are numerical elements that start counting with 1. To store the ranks of other array contents (e.g. page labels), you need a slightly different PHP code:

<code php>
$pages = array('A1','A2','A3','A4','A5','B1','B2-B4','B5');
// Do not mix the pages directly, but their positions
$indices = array_keys($pages);
shuffle($indices);
// Now save the ranks - and save the new sequence of pages in $random
$random = array();
for ($i=0; $i<count($indices); $i++) {
  // Save rank as above  $id = id('IV01', $indices[$i] + 1);
  put($id, $i + 1);
  // Save page in sequence
  $random[$i] = $pages[$indices[$i]];
}
// Set new page sequence
// After the last page we will continue on page "demography"
setPageOrder($random, 'demography');
</code>

===== Randomization II =====

If you work with the ''[[:en:create:randomization|randomization]] with the ''[:en:create:functions:random|random()]]' command in a [[:en:create:randomization|randomization]], you must store the random number thrown in the data set.

**Important:** We advise against using the function ''[[:en:create:functions:random|random()]]'' in the context of experiments. A [[:en:create:questions:random]] usually solves this task much better, see also the chapter [[:en:create:randomization]].

The following example assumes that you have created an internal variable with the ID "IV01_01".

<code php>
// Dice an integer between 1 and 2
$nubmer = random(1,2);
// Save the diced number in the data set
put('IV01_01', $number);
// And depending on it, display text module "text1" or "text2
if ($number == 1) {
  text('text1');
} else {
  text('text2');
}
</code>