====== getItems() ======

''array **getItems**(string //question ID//, string //comparison//, [int //answer code//])''

With the help of the function ''getItems()'', you can determine which items in a question are available, or which items have been checked off.

The function returns an array of question IDs, e.g. (1,2,4,5,6,9,10). These IDs can be added directly to another question by using the command ''question()''. By doing so, only the items that a person previously selected as being relevant can be displayed in a second question (e.g. only evaluate magazines that the participant reads), see [[:en:create:filter-items|Use Selected Items in Another Question]].

  * //Question ID//\\ The question's ID e.g. "AB01"
  * //Comparison//\\ Sets out the criteria of the items listed. It is important that the mode is put in quotation marks. The potential modes of comparison can be seen in the following table.
 
^Comparison^Description^
|'''all'''|all items in the question, useful e.g. for randomization. In this instance, an //answer code// is not specified.|
|'''>'''|lists all items with a greater answer code than the specified //answer code//. Therefore, a '''>''', in conjunction with an //answer code// of ''3'' in a scale of 1-5, would only select items for which a value over the middle of the scale was checked off.|
|''%%'>='%%'' or '''min'''|lists all items with at least the minimum //answer code//.|
|''%%'<='%%'' or '''max'''|items with the maximum //answer code//. Items with missing values(e.g. "no answer"), which technically have an answer code of -1, are not (!) listed here though.|
|'''<'''|items with a valid answer that is less than the //answer code// specified.|
|'''==''', '''=''', '''is''' or '''equal'''|items with the exact //answer code// specified.|
|''%%'!='%%'', ''%%'<>'%%''|Items that have __not__ received this //answer code//.|
|'''answered'''|items answered. **Note:** The option is not applicable for multiple choice selections, as a respondent cannot not answer the options.|
|'''missing'''|items not answered or missing.|
|'''valid'''|items with a valid answer, and therefore have not been left empty or given an answer of "do not know". **Note:** In a multiple choice selection, 'no answer' selected is also a valid answer. Here, use ' ''=='' ' in conjunction with answer code ''2'' to determine the options selected.|  
|'''invalid'''|items left empty or given an answer of "do not know".|

**Note:** As is the case with ''value()'', this function can only determine the answers of a participant on the page after the question. If the function is on the same page as the question, it does not work correctly because the answers will not yet have been transmitted to the server when the "next" button is pressed.

===== Use Selected Items in Another Question =====

In the following example, question ''AB01'' (a matrix question -- scale) is asked on page 1, in which the participant has to specify how often they read different magazines. 

On the following page 2, only items used at least "rarely" (answer code 2) should be displayed.

This example assumes that ''AB02'' has just as many items as ''AB01''. In addition, matching items must also have the same ID. Thus, item 1 could be "mirror" in both questions, and item 2 could be "star".

**Tip:** The most simple way to achieve this is by creating a question, duplicating it, and only changing the type of question and question text in the copy.

<code php>
// page 2
// determine items used at least "rarely" (2)
$itemlist = getItems('AB01', 'min', 2);
// only show these items in AB02
question('AB02', $itemlist);
</code>

The question ''AB04'' should now be asked on page 3 -- but only for the items, which according to ''AB01'', are used no less frequently than "often" (answer code 3).
 
Question ''AB04'' must also have the same items with the same IDs as question ''AB01''.

<code php>
// page 3
$itemlistB = getItems('AB01', 'min', 3);
// only show these items in question AB04
question('AB04', $itemlistB);
</code>

**Tip:** Please also read the chapter [[:en:create:filter-items|Use Selected Items in Another Question ]]


===== Further Examples =====

<code php>
// list of items, for which specifically "never" was selected
$itemlist = getItems('AB01', '==', 1);

// list of items, for which a maximum of 'rarely' was selected
$itemlist = getItems('AB01', '<=', 2);

// list of all items with a valid answer
$itemlist = getItems('AB01', 'valid');

// list all items of the question
$itemlist= getItems('AB01', 'all');
html('<p>The question shows '.count($itemlist).' Items.</p>');

// list of all items answered with never (1) or daily (4)
$list1 = getItems('AB01', '==', 1);
$list2 = getItems('AB01', '==', 4);
$itemlist = array_merge($list1, $list2);
</code>

In the following example, the combination of ''getItems()'' with the PHP function ''count()'' is shown. The function ''count()'' reveals the length of an array. As a result, for example, it can be checked whether the minimum of a certain number of items fulfil the criterion from ''getItems()''.   


<code php>
// determine unanswered items in question AB01
$missing = getItems('AB01', 'missing');
// if at least one of them is missing, then the question should be shown again
if (count($missing) > 0) {
  question('AB01');
}
</code>

**Tip:**  Please read the guide to the function ''[[:en:create:functions:repeatpage|repeatPage()]]'' for more information regarding the previous example.