RUSSWURM
    SoSciSurvey und PHP • Russwurm

    SoSciSurvey und PHP

    Inhalt



    Einführung

    Dieses Dokument ist eine kurze Einführung in die Nutzung von SoSciSurvey [1] mit PHP. Das Dokument entstand aus einer Bachelorarbeit und alle dafür verwendeten PHP Integrationen werden hier zusammengefasst.

    Das Dokument ist KEINE Dokumentation und erhebt auch KEINEN Anspruch auf Vollständigkeit, es ist eher eine Dokumentation der „lessons-learned“. Das Dokument stellt auch keine Best Practices für PHP Code dar.

    Tiefergehende Dokumentationen findet man bei PHP[2] und bei PHP für SoSciSurvey[3].

    Begriffe

    Zu Beginn kurz die wichtigsten Begriffe und in eckigen Klammern ein Beispiel für einen Bezeichner.

    Rubriken [TE]

    Rubriken kann man sich als Kategorie oder Folder vorstellen. Rubriken haben immer eine Kennung mit zwei Buchstaben, welche auch für den Zugriff auf die Items innerhalb der Rubrik verwendet werden, z.B. "TE". Innerhalb einer Rubrik findet man Texte und Fragen.

    Fragen [TE01]

    Fragen werden für den Fragebogen verwendet und können unterschiedliche Typen haben. Fragen bekommen automatisch die Bezeichnung der Rubrik und werden dann durchgehend durchnummeriert, z.B. "TE01".

    Item [TE01_01]

    Innerhalb von Fragen kann es einzelne Items geben, das sind die Punkte die im Fragebogen abgefragt werden. Items werden von 01 beginnend durchnummeriert.

    Texte [TE01_02]

    Texte werden im Fragebogen verwendet und bekommen automatisch die Bezeichnung der Rubrik und einer hochzählenden Nummer.

    Skalen

    Skalenwerte beginnen bei SoSci immer mit 1 und werden dann hochgezählt. Der Skalenwert -9 wird für nicht beantwortet verwendet.

    PHP Chunks

    Im folgenden kurze PHP Codes für oft verwendete Aufgaben.

    WICHTIG: PHP Code wird immer am Server ausgeführt, daher muss die Webseite zuerst zum Server geschickt werden, bevor der Code ausgeführt wird. Der PHP Code wird also immer ganz zu Beginn einer neuen Seite ausgeführt (bevor die Seite dargestellt wird) und kann daher nicht auf Werte innerhalb dieser Seite zugreifen. Daher den Code für Variablenauswertungen immer auf der NÄCHSTEN Seite einbinden.

    Header Parameter setzen

    Damit können Parameter im Header der Seite gesetzt werden. Sinnvoll um OpenGraph Daten einzubinden, z.B. für eine bessere Vorschau mit Bild in Social Media. Das folgende Beispiel setzt einen Titel und eine Beschreibung sowie ein Vorschaubild. Wenn man seine Umfrage über Facebook o.ä. teilt, sieht das gleich viel besser aus.

    pageHead('
  <meta property="og:url" content="https://www.soscisurvey.de/TE/" />
  <meta property="og:image" content="https://www.soscisurvey.de/TE/XXX.jpg" />
  <meta property="og:title" content="Verhaltensweisen von Student*innen" />
  <meta property="og:description" content="Studie zu ..." />
');

    CSS der Seite ändern

    Damit können Styleinformationen für die komplette Seite geändert werden. Das folgende Beispiel ändert die Logo Formattierung. Das Keyword !important wird verwendet um eventuell existierende Parameter in CSS zu überschreiben. Das kann sehr hilfreich sein, da man den restlichen CSS Code nicht kennt und damit nie genau weiß, was wann wo wie gesetzt wird ;)

    pageCSS('
   div#S2Logos {
      margin-bottom:0 !important;
   }
');

    Fortschrittsbalken anpassen

    Während der Umfrage wird ein Fortschrittsbalken angezeigt, damit Teilnehmer in etwa wissen, wie viel noch zu beantworten ist. Dieser Balken wird auf Basis aller Seiten berechnet und gibt daher falsche Werte an, wenn man einige Extraseiten hat, welche nicht angezeigt werden.

    Mit folgender Option des Kommandos option() kann man angeben, bis zu welcher Seite der Fortschrittsbalken berechnet wird:

    option('progress.last','done');

    Variablenzugriff

    Der Zugriff auf die Variablen des Fragebogens erfolgt mit dem Kommando value(). Die Variablen haben immer zwei Buchstaben von der Rubrik und eine zweistellige Zahl, z.B. TE01. Je nach Variablentyp, können noch mehrere Items verwendet werden, welche dann mit TE01_01, TE01_02, usw. benannt werden.

    Bei Fragen des Typs Mehrfachauswahl beinhaltet die Variable TE01 die Anzahl an ausgewählten Optionen.

    Bei Dropdowns beinhaltet die Variable die Nummer der gewählten Option, beginnend mit 1.

    Textausgabe

    Bei SoSci kann ein Text nicht direkt ausgegeben werden, sondern muss über die Funktionen show() oder html() ausgegeben werden.

    Das Kommando html() wird genutzt, um Text direkt im Fragebogen auszugeben.

    Das Kommando show() benutzt wird, um eine Textvariable auszugeben, wobei hier auch noch Platzhalter übergeben werden können. Platzhalter werden in SoSci jeweils in %-Zeichen eingeschlossen.

    html('Bitte geben Sie jetzt alle Werte an.');
show('TX02', 
   ['%person%' => 'Frau']
);

    Filter, Weiterleitungen

    Es gibt in SoSci auch einfache Filter für Fragen, allerdings kann man Filter schneller und viel flexibler über PHP umsetzen. Hier ein Beispiel, welches auf eine andere Seite weiterleitet, wenn die Variable AL03_01 einen Wert kleiner 18 hat, also eine typische Altersabfrage.

    Die Weiterleitung erfolgt mit goToPage() und wird sofort ausgeführt, daher sollte dieser Code zu Beginn einer Seite aufgerufen werden, damit die restliche Seite nicht mehr dargestellt wird.

    // filter for users younger than 18
if (value('AL03_01') < 18) {
   goToPage('endfast');
}

    Hier ein weiterer Filter, der immer dann weiterspringt, wenn die Variable AL05 den Wert 1 oder 2 hat, also bei einem Dropdown die erste oder zweite Option ausgewählt wurde.

    // filter for users having "Pflichtschule" or "Lehre"
if ( (value('AL05') == 1) || (value('AL05') == 2) ) {
	goToPage('endfast');
}

    Platzhalter

    In allen Texten, Fragen und Items können Platzhalter eingesetzt werden. Diese Platzhalter werden immer von %-Zeichen eingeschlosssen. Also %AGE% wäre ein solcher Platzhalter, der dann über PHP verändert bzw. gesetzt werden kann.

    In PHP erfolgt das Setzen von Platzhaltern über das Kommando replace().

    Gendern

    Eine Variante um Texte je nach ausgewähltem Geschlecht entsprechend anzupassen, ist die Verwendung von Platzhaltern. Auch dieser Code muss zu Beginn einer Seite ausgeführt werden und kann erst auf einer Seite NACH Auswahl des Geschlechts verwendet werden.

    Hier ein Beispiel, welches in AL04 die Geschlechtsauswahl gespeichert hat:

    // replacement text blocks, assuming 1=männlich, 2=weiblich, 3=divers
$gender_replace = [
   'gen_ein' => ['ein', 'eine', 'ein*e'],
   'gen_in' => ['', 'in', '*in'],
   'gen_einen' => ['einen', 'eine', 'eine*n'],
   'gen_der' => ['der', 'die', 'der*die']
];

// getting the gender var
$gender = value('AL04');

// if something goes wrong, take "divers"
if ( ($gender < 1) || ($gender >3) ) {
   $gender = 3;
}

// replacing all the vars
foreach( $gender_replace as $key_gen => $val_gen) {
   replace('%' . $key_gen . '%', $val_gen[$gender-1]);
}

    Buttons für "Weiter" und "Zurück" ändern

    Die Buttons für die nächste und die vorige Seite können angepasst werden. Das ist besonders hilfreich, wenn man eine Seite "verstecken" möchte. Das folgende Beispiel setzt den "Weiter" Button auf die letzte Seite und damit werden alle Seiten dazwischen übersprungen. 

    setNextPage('end');

    Parameter aus URL lesen

    Parameter in der URL können verwendet werden um zusätzliche Informationen in einen Fragebogen zu übergeben, z.B. Aktivieren von Debugging oder auch Parameter je nach Fragebogenlink.

    Hier ein Beispiel um den Parameter "code" und "debug" auszulesen aus der URL"https://www.soscisurvey.de/TE/?code=intern&debug=on

    $code = readGET('code');
$debug = readGET('debug');

    Datenbank für Inhalte

    Es gibt bei SoSci eine eigene Datenbank für die Benutzung mit PHP, die NICHT gleich der Fragebogendatenbank ist. Es ist also eine eigene, unabhängige Datenbank die bestehen bleibt, solange das Projekte besteht. Damit ist diese Datenbank optimal um Werte zwischen Fragebögen auszutauschen oder generell Werte längerfristig abzulegen.

    Im folgenden die Kommandos um etwas in der Datenbank zu speichern und wieder abzurufen. Die Speicherung erfolgt dabei immer mit einem eindeutigen Key und danach einem String oder einem Array.

    dbSet('KEY3672', $dbResult); // store the array $dbResult
$dbResult = (array)dbGet('KEY3672'); // read the array $dbResult

    Es gibt auch die Möglichkeit alle Einträge mit einem bestimmten Keypräfix zu laden, damit kann man alle gespeicherten Einträge abrufen:

    $entries = dbLoad('KEY');
foreach ($entries as $key => $val) {
   // whatever
}

    Balkendiagramm als Text

    Das folgende Beispiel ist ein gespeicherter Text als HTML Code, welcher einen einfachen Balken mit einem Mittelwert darstellt. Dieser Balken kann dann jederzeit mit PHP in einer Seite dargestellt werden:

    show('TX03', [
   '%min%' => 0,
   '%max%' => $scaleEnd,
   '%interval_percent%' => $val['interval_start'],
   '%interval_width%' => $val['interval_width'],
   '%mean_offset%' => sprintf("%.0f", $newPercent),
   '%mean_value%' => sprintf("%.0f", $newSum)
]);

    Und hier der entsprechende Texteintrag als "TX03":

    <style>
   .wrapper { width: 100%; height: 50px; position: relative; }
   .container { width: 100%; height: 100%; background-color: #f4f4f4;
      position: relative; }
   .mean { width: 6px; height: 100%; background-color: orange;
      position: absolute; left: 10%; transform: translateX(-3px); }
   .mean-value { position: absolute; left: 10%; text-align:center; 
      bottom:3px; }
   .confidence-interval { width: 20%; height: 100%; 
      background-color: #f0d0b0; position: absolute; left: 60%; }
   .label-left, .label-right { position: absolute; top: 50%; 
      font-size: 14px; color: #333; }
   .label-left { left: 0; padding: 0 0 0 0.5rem; 
      margin: -0.5rem 0 0rem 0px; }
   .label-right { right: 0; text-align:right; padding: 0 0.5rem 0 0; 
      margin: -0.5rem 0 0rem 0px; }
   .centered-text { transform: translateX(-50%); }
   @keyframes key-pulse {
      0% { transform: scale(1); opacity: 1; }
      50% { transform: scale(1.2); opacity: 0.5; }
      100% { transform: scale(1); opacity: 1; }
   }
   .pulse { animation: key-pulse 1s ease-in-out infinite; }
}
</style>

<div class="wrapper">
    <div class="mean-value" style="left:%mean_offset%%;">
        <div class="centered-text">%mean_value%</div>
    </div>
</div>

<div class="wrapper">
    <div class="container">
        <div class="confidence-interval" style="left:%interval_percent%%;width:%interval_width%%;"></div>
        <div class="mean pulse" style="left:%mean_offset%%;"></div>
    </div>
    <div class="label-left">%min%</div>
    <div class="label-right">%max%</div>
</div>

    Das Beispiel zeigt generell die Möglichkeit mit PHP über Platzhalter beliebigen Inhalt in CSS oder HTML der Seite zu integrieren.

    Genereller PHP Code für alle Seiten

    PHP Code kann auch für das gesamte Projekt, also unabhängig von den einzelnen Seiten unter "PHP-Funktionen" abgelegt werden. Alle Funktionen die dort gespeichert werden, sind von allen Seite jederzeit verfügbar. Das ist auch hilfreich, da die Codegröße pro Seite beschränkt ist. Hier ein Beispiel für eine Funktion die immer ganz hilfreich sein kann zum Umrechnen von Skalenwerten: 
    /**
<li>Converting into a new scale - new scale always starts at 0
</li>
<li>@param 	$value		value to convert
</li>
<li>@param	$min		min value in original scale
</li>
<li>@param	$max		max value in original scale
</li>
<li>@param	$maxScale	max value in target scale
</li>
 */
function convertScale( $value, $min, $max, $maxScale) {
	return (($value - $min)/($max - $min)) * $maxScale;
}

    Quellen und weitere Information

    [2]: Offizielle PHP Dokumentation auf https://www.php.net/docs.php
    [3]: Offizielle SoSciSurvey PHP Dokumentation https://www.soscisurvey.de/help/doku.php/en:create:functions
    [1]: SoSciSurvey https://www.soscisurvey.de