====== reference() ======

''string **reference**()''

If a reference in the [[:en:survey:url|URL to the Questionnaire]] was transferred, the function ''reference()''  will return it. The reference can have information concerning the participant encoded within it, which the questionnaire can use straightaway for filtering (see example 2).

**Tip:** The reference can also be integrated into questions, text elements and the function ''[[:en:create:functions:redirect|redirect()]]'' with the help of the [[:en:create:placeholders#predefined_placeholders|predefined placeholder]]  ''%reference%''.


===== Example 1 =====

In the following example, the reference is merely displayed.


<code php>
html('<p>Your reference: <strong>'.reference().'</strong></p>');
</code>

The placeholder ''%reference%'' has the same effect here:

<code php>
html('<p>Your reference: <strong>%reference%</strong></p>');
</code>


===== Example 2 =====

The use of the reference can be useful if other information is encoded within it. In the following example, social scientists would have "Axxx" as a reference (e.g. A100, A201, A991), and natural scientists would have a "BXXX" reference (e.g. B100, B201, B990) in the URL.

Depending on the reference, question "AB01" or "AB02" will now be displayed. In order to do so, the first character of the reference has to be extracted by using ''{0}''. PHP's own function ''[[http://php.net/manual/en/function.strtoupper.php|strtoupper()]]'' ensures potential lower case letters are converted into upper case.

<code php>
$ref = strtoupper(reference()); // identify reference and convert into upper case 
if (strlen($ref) < 1) {
  // No reference submitted (less than 1 character)
  goToPage('next');
} elseif ($ref{0} == 'A') {
  question('AB01');  // question for social scientists
} elseif ($ref{0} == 'B') {
  question('AB02');  // question for natural scientists
} else {
  // No valid reference submitted
  goToPage('next');
}
</code>
