====== Check Responses ======

SoSci Survey provides features that allow you to check a participant's responses. If the automatic check is insufficient then individual checks can be added in addition to these.

**Advice:** A general check to verify the formal correctness of responses can be problematic under certain circumstances. There are always participants who "just want to view" a questionnaire. Normally, these participants leave most questions unanswered or fill in blatantly pointless responses (e.g. age: 999 years old). On the other hand, if participants are made to provide information that is formally correct, the result of this is a seemingly complete data record. When using [[:en:results:variables|Variable MISSING]] to quickly clear up any empty data records, formally correct yet meaningless data goes often unrecognized and this effectively "pollutes" the data record.

**Advice:** An automatic "probe" (ask the question again and then, if necessary, also accept a missing or wrong answer) is being developed but is not available at this point in time. A [[#probe|probe]] can be installed for individual questions/items through a filter.

===== Force Response =====

Checking questions are complete makes sense, if...

  * there is a risk that individual items are overlooked in a question (e.g. scale)
  * if the response to a question (e.g. selection) is particularly important or
  * if the response to a filter question ([[:en:create:filters|Filters and Conditional Questions]]) influences the rest of the questionnaire.

In order to activate the completeness check for a question, select the question in the **List of Questions**. Depending on the type of question, you can force a response to the question in the //Checking the answers// tab or by selecting the box next to //Check for completion//. For some types of questions (e.g. text input) you can set the desired answer format in detail.

{{:de:create:scr.insist.option.png?nolink|Option to Make Answers Compulsory}}

{{:de:create:scr.insist.tab.png?nolink|Tab to Make Answers Compulsory}}

Depending on the type of question, an answer can be made compulsory for individual items (e.g. in a scale); not just for the whole question. Select the respective item in the **List of Questions** and select the corresponding box. If it is already a compulsory question then this option is not offered for individual items.

Compulsory questions and items are displayed in the questionnaire with a small symbol {{:symbol.required.png?nolink|Compulsory Question/Item}}.

**Advice:** Making participants answer the question does not make sense for some types of questions -- particularly multiple choice questions. However, for these types of questions, a minimum number of answers that have to be selected can be set. 

**Advice:** As long as additional input fields are defined for individual answer options in a selection or a multiple choice (e.g. for "other"; [[selection-textinput|Free Text Inputs Within a Selection]]), then making the question compulsory means these fields will also have to be filled out if this option is selected. 

===== Minimum Number of Selections =====

It does not make sense to make answers compulsory for multiple choice questions (with the exception of using free input fields, see above), when "no answer" can also be a valid. However, if the participant should choose a certain number of options, this can be set in the //Checking the answers// tab of the question.

A maximum number of selections the participant can choose can also be set here (i.e. a certain number cannot be exceeded). By using [[:en:glossary#javascript|JavaScript]], SoSci Survey makes sure the number of selections able to be chosen are limited

**Tip:** If you use a "none of the given options" option, then select this in the **List of Questions** and enable the //Exclusive Option// option. If selected, this option cannot be selected together with other options.

===== Entering Numbers =====

If you want to only allow numbers to be entered in an free text input field, open the detailed view of the respective item in the **List of Questions** or with the edit icon ({{:button.edit.gif?nolink|edit}}). Choose either the "digits" or "decimal number" option in //Text Input Restrictions//. 

As another option, you can set the number range in //Minimum// und //Maximum//.

===== Additional Text Formats =====

The following additional text formats are predefined:

  * //Email address// -- here, the email address is checked to see if it is formally correct. Whether or not this email address actually exists is __not__ checked.
  * //Characters// -- this limits the input to only letters from A to Z. Umlauts or spaces are __not__ allowed.
  * //Year// -- four digits ranging from 1000 to 2500. If you need a different range, select "numbers" and specify the range using //minimum// and //maximum//.


===== Regular Expressions =====

You can also check for regular expressions in text input. If a regular expression is given then other text input restrictions are ignored.

Regular expressions are powerful tools -- but it is somewhat challenging to understand them. You can find a great manual in English under [[http://www.regular-expressions.info/|regular-expressions.info]].

===== Customizing Error Messages =====

Under **Text Elements and Labels**  you can customize all error messages in //Other Texts//. Please note, wording cannot be customized for individual questions, except when you use individual answer checking (see below). 

With the PHP function [[:en:create:functions:getanswermissing|getAnswerMissing()]] and [[:en:create:functions:listfails|listFails()]] you are able to check which questions or items were not answered. By using [[:en:create:functions:text|text()]] you can then display customized error message text -- but only in addition to the predefined error message.

===== Customized Response Check =====

If the predefined checks are insufficient, you can program a customized response check using a filter and the [[:en:create:functions:repeatpage|repeatPage()]] function.

The PHP code used to check the answer must be put on the page __after__ the question at the top. Therefore, if the question that needs to be checked is on page 2 then the PHP code that checks the question must be put at the top on page 3.

**Tip:** Further details about programming filters can be found under [[:en:create:filters|Filter Questions and Filters]].

**Tip:** Use the function ''[[:en:create:functions:markfail|markFail()]]'' to highlight inputs with incorrect responses.

Display an error message by passing the ID of a text element to ''repeatPage()'' (see below). Alternatively, you may simply display a text element using [[:en:create:functions:text|text()]] when answers are missing/incorrect. When you set up the text element make sure the text is displayed in the style of a //warning// -- then it will have the same format as the standard error messages.

==== Example: All Items or None at All ====

The following PHP code checks whether all items in a scale were answered -- or none at all. The question's ID (in example ''AB01'') must therefore be changed to reflect the actual question ID and the error message must be saved as a text element. If this text element's ID is not "error_AB01" then the ID must also be customized.

<code php>
// Create a list of all items in the question
$items = getItems('AB01');
// Determine items answered
$answered = getItems('AB01', '>', 0);
// Error and go back if not all or none were answered
if ((count($answered) > 0) and (count($answered) < count($items))) {
  repeatPage('error_AB01');
}
</code>


===== Probe =====

It can make sense to probe when answers are missing for questions that are important for data analysis, or for questions that were simply missed out (e.g. items in long rows).

Until a corresponding function is available in SoSci Survey, you can probe with the help of a filter ([[filters|Filters and Conditional Questions]]). Please see below:  

  - Insert an additional page directly after the question in **Compose questionnaire**.
  - Create a filter on the page which jumps directly onto the next page when the correct answer is given, but shows the question again if this is not the case (see example below).

**Advice:** ScoSci Survey will display a warning to you, as the project leader, because the same questions are used on different pages in the questionnaire. Usually this would indicate a problem, but here it is intended. Therefore you can ignore this piece of information. The participant will not see this warning.

The following example checks if all items in the AB01 (scale) group of questions were answered. If this is not the case, the text block "missingAB01" will be displayed (must initially be created in **Text Elements**) and the missing items will be displayed again.

<code php>
$miss = getItems('AB01', 'is', -9);
if (count($miss) == 0) {
  // go directly to next page if no item is missing
  goToPage('next');
}
// display error message
text('missingAB01');
// show the question again; this time only the missing items
question('AB01', $miss);
</code>