markFail()

void markFail(string variableID)

The function markFail() is used in conjunction with a individual response check (Check Responses: Customized Response Check) and the function repeatPage(). This means an input field is highlighted in such a way so that the participant can recognize where information is not correct.

• variableID
  The ID of a variable in the data record (see Variables Overview).

There are two effects to using markFail(): first of all, the input field will be highlighted visually, and secondly, the response is counted as a missing answer when calculating the variables MISSING and MISSREL (Additional Variables in the Data Record). The latter is particularly important if markFail() is used without repeatPage().

In the following example, the participant is asked how many hours and minutes a person watches television every day on page 1 of the questionnaire. The answers are to be written in the free text input fields “AB01_01” and “AB01_02”. In addition, there is a multiple-choice selection option “I don't watch any television” with the ID “AB02_01”.

On page 2, whether something has been entered in one of the text input fields is checked – or if the selection field is highlighted. If none of this applies, the page is redisplayed, the text element “missing_tv” is displayed as an error message and the input field is highlighted.

if (
  (trim(value('AB01_01')) == '') and
  (trim(value('AB01_02')) == '') and
  (value('AB02_01') != 2)
) {
  markFail('AB01_01');
  markFail('AB01_02');
  repeatPage('missing_tv');
}

Here, the participant is asked the hours and minutes and a residual option – just like in example 1. This time, however, in a combined question with 10 different forms of media. The number of hours are asked in the first column (question “AC01”), the number of minutes in the second column (“AC02”), and a multiple-choice selection “AC03”) serves as the third column.

On the following (!) page, it is now checked using PHP code if information was given in each line, or if the selection field was highlighted. If not, the page is redisplayed and the lines with missing information are highlighted.

$missing = false;
$items = getItems('AC01', 'all');
foreach ($items as $item) {
  $idH = id('AC01', $item);
  $idM = id('AC02', $item);
  $idX = id('AC03', $item);
  if ((trim(value($idH)) == '') and (trim(value($idM)) == '') and (value($idX) != 2)) {
    markFail($idH);
    markFail($idM);
    $missing = true;
  }
}
if ($missing) {
  repeatPage('dateandtime');
}

Sometimes the error messages should be adjusted more precisely to the missing variables. The following PHP code demonstrates how to select the appropriate texts and avoid the duplicate display.

// Variables and related error codes
$checks = [
  'AW01' => 'Text1',
  'AW02' => 'Text2',
  'AW03_01' => 'Text3',
  'AW03_02' => 'Text3',
  'AW03_03' => 'Text3',
  'AW03_04' => 'Text4',
  // u.s.w.
];
 
// Check all variables, mark and collect error codes
$messages = [];
foreach ($checks as $variable => $text) {
  $antwort = value($variable);
  if ((trim($answer)=== '') || ($answer < 1)) {
    markFail($variable);
    $messages[] = $text;
  }
}
 
// If necessary, display error messages and repeat page
if (!empty($messages)) {
  $messages = array_unique($messages);
  html('<div class="feedback" role="status">');  // Red frame
  foreach ($messages as $text) {
    text($text, 'spacing=10');
  }
  html('</div>');
  repeatPage();
}

The PHP code consits of three parts. In the first part, the variables to be checked are defined in an array and which error message should be displayed in each case if the variable is not answered.

In the second part, all variables are then checked individually in a FOR loop. The (trim($response) === '') is only necessary if you also want to check text input. Otherwise ($response < 1) checks for an error code. Unanswered input fields are directly marked with markFail() and the text identifier associated with the error message is noted in the array $messages.

The third part then checks if there are messages in the array $messages, duplicates are removed with array_unique(). The <div> in the HTML code provides the formatting as a feedback message (e.g. marked by a red frame) and within this the error messages are then output. Finally, the repeatPage() takes care of redisplaying the page.