====== registerVariable() ======
''void **registerVariable**(string //variableName//)''
In PHP, a variable is normally only valid within __one__ PHP code element. By using ''registerVariable()'', a variable can be made available for all following PHP code elements.
* //variableName//\\ A string (in quotation marks) with the name of the variable. This cannot be the variable itself (e.g. ''$item''), a string with the name of the variable (e.g. 'item').
**Important:** Changes to variables are applied to subsequent PHP code only if the corresponding PHP code runs to the end. Functions such as ''repeatPage()'', ''goToPage()'' or ''pageStop()'' interrupt the execution so that the changes are not applied. Please note that this behavior varies depending on the function and program version. The use of [[:en:create:questions:internal|internal variables]] is a robust alternative.
===== Use with isset() =====
Many examples in the manual use ''registerVariable()'' together with the PHP function ''[[http://php.net/manual/de/function.isset.php|isset()]]'' to avoid multiple [[:en:create:randomization|Randomization]] or [[:en:create:rotation|Rotation]] functions -- for example if the questionnaire page is displayed again after "Next" because answers are still missing.
The function ''isset()'' determines whether a PHP variable has already been defined before. This way you can avoid that e.g. a list is created and merged if it has been defined before.
**Note:** The content of the variable is __not__ stored in the dataset and the PHP variable is deleted when the "last page" is reached (completion of the questionnaire). If the content of the variable (e.g. the order of a rotation) is relevant for the evaluation, you have to save it explicitly in the dataset using ''[[:en:create:functions:put]]''.
**Wichtig:** When using ''registerVariable()'' you have to be aware that the registered variable is defined for the whole rest of the interview. If one would like to use the combination ''registerVariable()'' and ''isset()'' again at another place, one should choose a __different name for the variable__. For example ''$itemsAB'' in the first PHP code and ''$itemsBC'' in the second.
Here is an example where the items of a question are mixed specifically:
// The bracket is only executed,
// if the variable $items has not yet been defined,
// at the first visit of this page - and only then,
// if there is no registerVariable($items) in the questionnaire before.
if (!isset($items)) {
// Here the items of question AB01 are retrieved and mixed
$items = getItems('AB01');
shuffle($items);
// And this is where SoSci Survey makes sure that the variable $items
// does not immediately forget them again, but rather keeps them for the complete
// remaining interview (including a possible
// call the current page again).
registerVariable($items);
}
// Here the content of the variable is now used
question('AB01', $items);
From now on the variable ''$items'' is defined on every further page in the questionnaire in every PHP code. If you would place the same PHP code on another page, then ''isset($items)'' would give the result ''true'', the negation with the exclamation mark ''!isset($items)'' would be ''false'' (not true). And so the bracket would not be executed, even if the variable ''$items'' should be used completely different the second time.
This example is taken from chapter [[:en:create:rotation]]. There you will also find examples of further applications.
===== Drag items of a question =====
In the following example, on page 1, three items are taken from the items in question "AB01". Following this, the question is asked with these three items -- and, on a later page, question "ABO2" is asked with these exact same three items.
// Take three items from question AB01
$itemlist = random_items('AB01', 3);
// Show the respective question
question('AB01', $itemlist);
// Register variable $itemlist
registerVariable($itemlist);
As the variable ''$itemlist'' was made available for other pages in the questionnaire, you can just carry on working with ''$itemlist'' in another PHP code element.
question('AB02', $itemlist);
===== Remember partial results/filter =====
On page 4 in the questionnaire, a rather complicated filter is used to determine whether the participant falls into group 1 (prospective clients or clients preparing to do business), or group 2 (current clients). Different questions will be shown later on the in the questionnaire resulting from this classification.
if (
(value('BB01') == 1) or
((value('BB02') < 3) and (value('BB04') == 2)
) {
$group = 1;
} else {
$group = 2;
}
registerVariable($group);
The variable ''$group'' can also be used later on in the questionnaire.
if ($group == 1) {
question('BX01');
} else {
question('BX02');
}
if ($group == 1) {
question('BX04', '1-3,5,6');
} else {
question('BX04', '1-5,7,9');
}
**Tip:** As the group will also be important in the analysis, the use of ''[[:en:create:functions:put|put()]]'' and, on later pages, ''[[:en:create:functions:value|value()]]'' would arguably be more effective here.
===== Content Rotation =====
4 questions ("AB01" to "AB04") are displayed with their associated text elements ("text1" to "text4) -- but in random order. Therefore, an array is shuffled on page 1 of the questionnaire and made available for the following pages with ''registerVariable()''. For further details, please see chapter [[:en:create:rotation|Rotation]].
$questions = array(
array('AB01', 'text1'),
array('AB02', 'text2'),
array('AB03', 'text3'),
array('AB04', 'text4')
);
shuffle($questions);
registerVariable($questions);
On the following four pages, each question and text element, which can be found in the corresponding position in the array, is displayed.
text($questions[0][1]);
question($questions[0][0]);
text($questions[1][1]);
question($questions[1][0]);
text($questions[2][1]);
question($questions[2][0]);
text($questions[3][1]);
question($questions[3][0]);