====== panelData() ======

''array **panelData()**''

Der Befehl ''panelData()'' liefert Informationen aus der **Adressliste**, falls das Interview durch einen personalisierten Link (z.B. aus einer Serienmail) gestartet wurde.

Der Befehl ''panelData()'' liefert eine Notiz aus der Liste der **Teilnahmecodes**, falls der Fragebogen die [[de:create:access|Zugriffsbeschränkung]] "Teilnahmecode" verwendet.


===== Rückgabewert (Adressliste) =====

Der Befehl ''panelData()'' liefert in einem Array die Zugehörigkeit des Teilnehmers zu einer Teilgruppe, den Zeitpunkt des Mail-Versands und die Daten, die als //benutzerdefinierte Daten// im Adresseintrag hinterlegt wurden:

<code php>
array(
  0 => (string) Teilgruppe
  1 => (string) Benutzerdefinierte Daten 1
  2 => (string) Benutzerdefinierte Daten 2
  3 => (string) Benutzerdefinierte Daten 3
  4 => (string) Benutzerdefinierte Daten 4
  5 => (string) Benutzerdefinierte Daten 5
  'subgroup' => (string) Teilgruppe
  'mailing' => (int) Nummer (ID) der Serienmail, in welcher der Einladungslink verschickt wurde
  'mailsent' => (int) Unix-Zeitstempel des Versand-Zeitpunkts
  
  // Nur für Teilnehmer mit Datenschutz-Modus "Personenbezogen" verfügbar, sonst NULL
  'firstname' => (string) Vorname
  'lastname' => (string) Nachname
  'gender' => (string) Geschlecht ('female', 'male', 'other' oder '')
  'email' => (string) E-Mail-Adresse
  'email.cc' => (string) E-Mail CC-Adresse
  'mobile' => (string) Mobiltelefonnummer
  'serial' => (string) Personenkennung
)
</code>

**Wichtig:** Die Funktion liefert nur dann ein Array, wenn das Interview durch Klick auf den personalisierten Link einer Serienmail gestartet wurde (sonst ''NULL''). Wenn der Teilnahmer nach einer Opt-In-Bestätigung automatisch zu einem Fragebogen weitergeleitet wird ([[:de:survey:opt-in-live]]), so ist das technisch äquivalent zum Klick auf den personalisierten Link einer Serienmail.

**Hinweis:** Falls für den Adressaten der [[de:survey:mailing#datenschutz-modus|Datenschutz-Modus]] "anonym" eingestellt wurde, liefert ''panelData()'' keine Daten (''NULL'').

**Hinweis:** Falls beim Versand der Serienmail individuelle Zeitpunkte verwendet werden, kann die Information zum Versandzeitpunkt (ähnlich wie bestimmte benutzerdefinierte Daten) die Vertraulichkeit  pseudonymer Adresseinträge aufheben und sollte nicht im Datensatz gespeichert werden. Falls der Adresseintrag den [[:de:survey:mailing#datenschutz-modus|Datenschutz-Modus]] "personenbezogen" verwendet, wird der Versandzeitpunkt automatisch in der Variable MAILSENT im Datensatz gespeichert und 'mailsent' liefert denselben Wert wie ''value('MAILSENT')''. Bei Adresseinträgen mit Datenschutz-Modus "pseudonym" oder "anonymisieren bei Abschluss des Interviews" ist der Versandzeitpunkt nur über ''panelData()'' verfügbar, um eine versehentliche De-Anonymisierung zu vermeiden.

**Hinweis:** Falls der Teilnehmer eine Einladung und eine Erinnerung erhalten hat, wird in ''%%'mailsent'%%'' der Zeitpunkt angegeben, wann die ursprüngliche Einladung verschickt wurde und in ''%%'mailing'%%'' steht die ID der ursprünglichen Einladung -- unabhängig davon, ob er den Link in der Einladung oder in der Erinnerung aufruft.


===== Rückgabewert (Teilnahmecodes) =====

Falls der Fragebogen die [[de:create:access|Zugriffsbeschränkung]] "Teilnahmecode" verwendet, liefert ''panelData()'' den verwendete Teilnahmecode und eine eventuell dazu hinterlegte Notiz:

<code php>
array(
  'serial' => (string) Teilnahmecode
  'note' => (string) Notiz zum Teilnahmecode
)
</code>

**Wichtig:** Der Fragebogen muss die Zugriffsbeschränkung "Teilnahmecode" verwenden, die Angabe eines Teilnahmecodes im [[:de:survey:url|Link zum Fragebogen]] reicht nicht aus. Der [[:de:create:placeholders|Platzhalter]] ''%caseSerial%'' hingegen liefert einen Teilnahmecode auch, wenn der Fragebogen öffentlich ist.


===== Beispiel: Daten zuspielen =====

Das folgende Beispiel geht davon aus, dass im Adresseintrag der Name des Unternehmens im benutzerdefinierten Feld 1 hinterlegt wurde. Nun soll der Namen des Unternehmens im Fragebogen als Inhalt für den Platzhalter ''%company%'' verwendet werden.

<code php>
$data = panelData();
if ($data === null) {
  // Fehlermeldung und Abbruch des Fragebogens,
  // falls der Fragebogen nicht via Serienmail aufgerufen wurde
  text('no data');
  buttonHide();
  pageStop();
}
$company = $data[1];
replace('%company%', $company);
</code>


===== Beispiel: Experiment in mehrwelliger Befragug =====

In diesem Beispiel registrieren sich Teilnehmer selbst für eine Studie ([[:de:survey:opt-in-live]]). Im folgenden sollen Teilnehmer der Kontroll- und Experimentalgruppe unterschiedliche Serienmails als experimentellen Stimulus erhalten. Deshalb müssen ihre Adresseinträge unterschiedlichen Teilgruppen zugeordnet werden. Dies erfolgt, indem je nach Zufallsziehung ([[:de:create:questions:random]]) eine von zwei Opt-In-Fragen angezeigt wird.

**Hinweis:** Eine [[de:create:questions:opt-in|Opt-in Frage]] kann einen neu registrierten Teilnehmer automatisch einer //Teilgruppe zuordnen//.

<code php>
if (value('RG01') == 1) {
  question('OI01');  // Opt-In-Frage OI01 setzt Teilgruppe "EG"
} else {
  question('OI02');  // Opt-In-Frage OI02 setzt Teilgruppe "CG"
}
</code>

Nach Opt-In-Bestätigung der E-Mail-Adresse wird der Teilnehmer automatisch zu einem zweiten Fragebogen weitergeleitet. Hier soll nun abhängig von der Gruppenzugehörigkeit der Stimulus aus Textbaustein "textEG" oder "textCG" angezeigt und entweder Serienmail 2 oder 3 verschickt werden.

<code php>
$info = panelData();
if ($info) {
  $group = $info['subgroup'];
  if ($group == 'CG') {
    text('textCG');
    mailSchedule(false, 2);
  } else {
    mailSchedule(false, 3);
  }
} else {
  // Fehlermeldung anzeigen, dass der Fragebogen nicht mit einem gültigen Teilnahmeschlüssel
  // aufgerufen wurde (z.B. nicht aus einer Serienmail heraus) oder dass der Adresseintrag
  // mittlerweile aus der Adressliste gelöscht wurde
  text('some-error');
}
</code>

Zur einfacheren Auswertung wäre es hier sinnvoll, die Gruppenzugehörigkeit via ''[[:de:create:functions:put]]'' im Datensatz des zweiten Fragebogens abzulegen. Folgender PHP-Code würde z.B. im IF-Teil des vorherigen PHP-Codes ergänzt, nachdem eine [[:de:create:questions:internal|interne Variable]] IV01_01 im **Fragenkatalog** angelegt wurde.

<code php>
$group = $info['subgroup'];
put('IV01_01', $group);
</code>


===== Beispiel: Zeit zwischen Einladung und Teilnahme =====

In diesem Beispiel werden Serienmails im Rahmen eines Random Experience Sampling zu zufälligen Zeitpunkten an die Teilnehmer verschickt. Für die Auswertung ist es wichtig, ob der Teilnehmer den Fragebogen binnen 30 Minuten ausgefüllt hat oder nicht. Allerdings soll der Versand-Zeitpunkt nicht im Datensatz gespeichert werden, weil dies die Anonymität gefährden könnte.

Mithilfe von ''panelData()'' kann der genaue Versandzeitpunkt nun ermittelt werden und damit die Verzögerung zwischen Versand der E-Mail und der Teilnahme. Die PHP-Funktion ''time()'' liefert die aktuelle Zeit als Unix-Zeitstempel, die Differenz ergibt die Verzögerung in Sekunden. Falls die Verzögerung mehr als 30 Minuten (1800 Sekunden) ist, wird in der [[:de:create:questions:internal|internen Variable]] IV01_01 der Code 2 gespeichert, sonst der Code 1.

Falls sich der Versand-Zeitpunkt nicht ermitteln lässt, wird der Code -1 gespeichert. Das kann passieren, wenn das Interview nicht mit einem Serienmail-Link gestartet wurde oder wenn der Adresseintrag zwischenzeitlich durch den Projektleiter oder den Teilnehmer gelöscht wurde.

<code php>
$info = panelData();
if ($info) {
  $sent = $info['mailsent'];
  $delay = time() - $sent;
  if ($delay <= 1800) {
    put('IV01_01', 1);
  } else {
    put('IV01_01', 2);
  }
} else {
  put('IV01_01', -1);
}
</code>