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 = 'AC01_'.sprintf('%02d', $item);
  $idM = 'AC02_'.sprintf('%02d', $item);
  $idX = 'AC03_'.sprintf('%02d', $item);
  if ((trim(value($idH)) == '') and (trim(value($idM)) == '') and (value($idX) != 2)) {
    markFail($idH);
    markFail($idM);
    $missing = true;
  }
}
if ($missing) {
  repeatPage('dateandtime');
}