Differences

This shows you the differences between two versions of the page.

--- en:create:functions:paneldata [26.06.2016 14:46]
s1305605 [Example]
+++ en:create:functions:paneldata [03.02.2018 22:15] (current)
admin Full update
@@ Line 1: / Line 1: @@
-====== panelData() ======
+====== panelData () ======
 ''array **panelData()**''
-The command ''panelData()'' provide the allocation of a participant to a subgroup (index 0) and the data, which is given as //user defined data// in the address records, in an array (indices 1 to 5).
+The function ''panelData()'' returns information from the **Addresslist** if the interview was started by a personalized hyperlink (e.g., from a mailing).
-**Important:** The function provide a value only, if the interview was started by click at the personalized link in a mass mail (else ''zero''). In case the participant is forwarded automatically to the survey, after an Opt-In-Confirmation, ([[:en:survey:opt-in-live]]), than this is equivalent to the click at the personalized link in a mass mail.
+===== Return Value =====
-===== Example =====
+The'' panelData ()'' command returns in an array including the address entries subgroup, the time of the mail dispatch, and the data stored as //user-defined data// in the address entry.
+<code php>
+array (
+=> (string) Subgroup,
+=> (string) User-defined data 1,
+=> (string) User-defined data 2,
+=> (string) User-defined data 3,
+=> (string) User-defined data 4,
+=> (string) User-defined data 5,
+  'subgroup' => (string) Subgroup,
+  'mailsent' => (int) Unix timestamp when the mail was sent
+)
+</code>
+**Important:** The function provide a value only, if the interview was started by click at the personalized link in a mass mail (else ''zero''). In case the participant is forwarded automatically to the survey, after an Opt-In-Confirmation, ([[:en:survey:opt-in-live]]), than this is equivalent to the click at the personalized link in a mailing.
+**Note:** If individual sending times are used for the mailing, the information on the sending time (like certain user-defined data) can remove anonymity and should not be stored in the data set. If the address entry is not anonymous, the sending time is automatically stored in the MAILSENT variable in the data set and 'mailsent' returns the same value as ''value('MAILSENT')''.
+===== Example: Importing data =====
 The following example is based on the assumption, that the name of the company is placed in field 1 of the address record. Now, the name of the company should be used as the content of the placeholder ''%company%''.
@@ Line 15: / Line 35: @@
 $data = panelData();
 if ($data === null) {
-  // error message and stop of the survey,
+  // Error message and abort of the questionnaire,
-  // if the survey was not opened by a serial letter
+  // if the questionnaire was not called up with a personalized link
   text('no data');
   buttonHide();
@@ Line 23: / Line 43: @@
 $company = $data[1];
 replace('%company%', $company);
+</code>
+===== Example: Experiment in two-wave survey =====
+In this example, participants register themselves for a study ([[:en:survey:opt-in-live]]). In the following, participants of the control and experimental group will receive different emails as experimental stimulus. Therefore, their address entries must be assigned to different subgroups. This is done by displaying one of two opt-in questions, depending on a randomly drawn code ([[:en:create:questions:random]]).
+**Note:** An [:en:create:questions:opt-in|Opt-in question]] can automatically assign a newly registered participant to a //subgroup//.
+<code php>
+if (value('RG01') == 1) {
+  question('OI01'); // Opt-In question OI01 sets subgroup "EG".
+} else {
+  question('OI02'); // Opt-In question OI02 sets subgroup "CG"
+}
+</code>
+After opt-in confirmation of the e-mail address, the participant is automatically forwarded to a second questionnaire. Depending on the group affiliation, the stimulus from text module "textEG" or "textCG" is to be displayed and either mailing 2 or 3 is to be sent.
+<code php>
+$info = panelData();
+if ($info) {
+  $group = $info['subgroup'];
+  if ($group == 'CG') {
+    text('textCG');
+    mailSchedule(false, 2);
+  } else {
+    mailSchedule(false, 3);
+  }
+} else {
+  // Display error message that the questionnaire does not contain a valid participation key.
+  // (e.g. when not started from a mailing) or that the address entry was called after
+  // the address record had been deleted from the address list
+  text('some-error');
+}
+</code>
+For easier analysis, it would make sense to store the group membership via ''[[:en:create:functions:put]]'' in the data set of the second questionnaire. For example, the following PHP code would be added to the IF part of the previous PHP code after an [[:en:create:questions:internal|internal variable]] IV01_01 was added in the **List of Questions**.
+<code php>
+$group = $info['subgroup'];
+put('IV01_01', $group);
+</code>
+===== Example: Time between invitation and participation =====
+In this example, mailings are sent to the participants at random times as part of random experience sampling. It is important for the evaluation whether the participant has completed the questionnaire within 30 minutes or not. However, the dispatch time should not be saved in the data record because this could jeopardise anonymity.
+With the help of ''panelData ()'' the exact sending time can now be determined and thus the delay between sending the email and the participation. The PHP function ''time ()'' returns the current time as a Unix timestamp, the difference is the delay in seconds. If the delay is more than 30 minutes (1800 seconds), the code 2 will be stored in the [[:en:create:questions:internal|internal variable]] IV01_01, otherwise the code 1.
+If the sending time cannot be determined, code -1 is stored. This can happen if the interview was not started from a mailing link or if the address entry has been deleted in the meantime by the project manager or the respondent.
+<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>