Translations of this page:
 

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 internal variables is a robust alternative.

Use with isset()

Many examples in the manual use registerVariable() together with the PHP function isset() to avoid multiple Randomization or 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 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 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 put() and, on later pages, 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 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]);
en/create/functions/registervariable.txt · Last modified: 21.04.2024 20:29 by admin
 
Except where otherwise noted, content on this wiki is licensed under the following license: CC Attribution-Share Alike 4.0 International
Driven by DokuWiki