====== Einführung in PHP-Code ======

Das Element //PHP-Code// im Fragebogen ([[questionnaire#php-code|Einen Fragebogen zusammenstellen]]) erlaubt sehr flexible Funktionen im Fragebogen. Angefangen bei Filtern ([[filters|Filterfragen und Filter]]), über Platzhalter ([[placeholders|Platzhalter]]) und kombinierte Fragen ([[combine|Kombinierte Fragen]]), bis hin zu der Anzeige von nur solchen Items, die in einer vorhergehenden Frage angekreuzt wurden.

Der kleine Nachteil dabei: Man muss programmieren.

Dieses Kapitel versucht, einen kleinen Einstieg in die Programmierung mit PHP zu geben. Keine breite Einführung in die Programmiersprache, sondern nur gerade so viel, wie man für fortgeschrittene Fragebögen und/oder Filter braucht.

===== PHP-Code im Fragebogen verwenden =====

Damit man überhaupt PHP-Code im Fragebogen verwenden kann, muss man zunächst einen **Fragebogen zusammenstellen**. Hat man einen Fragebogen zum Bearbeiten geöffnet, so werden oben die Seiten angezeigt, links die aktuelle Fragebogenseite und rechts die Bausteine für den Fragebogen: Fragen, Textbausteine, etc.

Ganz oben bei den Bausteinen gibt es einen Baustein "PHP-Code" - diesen kann man genauso wie Fragen in die Fragebogen-Seite hineinziehen.

{{scr.questionnaire.insertphp.png?nolink|PHP-Code in den Fragebogen einfügen}}

Nach dem Einfügen des //PHP-Code//-Elements erscheint im Fragebogen ein Texteingabefeld, in das man PHP-Code eingeben kann.

===== Bequemer programmieren (Fragen und Texte) =====

Es ist i.d.R. müßig, die Fragen per Hand in den PHP-Code einzutippen. SoSci Survey macht es Ihnen ein wenig einfacher: Wenn man eine Frage (aus dem Fragebogen oder aus der Liste rechts) in ein Element PHP-Code hineinzieht, dann wird der Code automatisch geschrieben.

So braucht man Fragen und Textbausteine nicht per Hand einzutippen. Um einen Filter zu erstellen, kann man zunächst die IF-Konstruktion ([[filters|Filterfragen und Filter]]) verwenden.

{{scr.questionnaire.element-to-php.png?nolink|Ein Fragebogen-Elemente in PHP-Code umwandeln}}

**Hinweis:** Wenn eine Frage erstmal im PHP-Code steht, dann gibt es keinen Weg zurück. Natürlich kann man die Frage im PHP-Code löschen und aus der Auswahl rechts neu in den Fragebogen einfügen.

===== Funktionen =====

Ein Computer ist eine Maschine und man muss ihm ganz genau sagen, was man von ihm möchte. In der Programmiersprache heißt das Befehl. Die sinnvolle Aneinanderreihung von Befehlen ergibt ein Programm.

Die Befehle in PHP nennt man auch Funktionen. Eine Funktion sieht etwa aus wie folgt:

<code>
question('AB01');
</code>

Die eigentliche Funktion heißt ''question''. Das ist in SoSci Survey der Befehl, um eine Frage anzuzeigen. Dahinter folgen Klammern. Da jede Funktion von Klammern gefolgt wird, schreibt man den Funktionsnamen üblicherweise so: ''[[:de:create:functions:question|question()]]''

In den Klammern steht im Beispiel ein so genannter Parameter. Damit gibt man an, was die Funktion genau machen soll. Der Parameter im Beispiel ist ''%%'AB01'%%''. Die einfachen Anführungszeichen zeigen an, dass es sich um einen Text, auch String genannt, handelt. Man könnte übrigens auch doppelte Anführungszeichen verwenden: ''%%"AB01"%%''.

Da man i.d.R. mehrere Befehle aneinanderreiht, benötigt man noch ein Zeichen, um die Befehle zu trennen. Das ist der Strichpunkt (;). In PHP muss __jeder__ Befehl mit einem Semikolon abgeschlossen werden - sonst gibt es eine Fehlermeldung.

**Tipp:** PHP-Code bzw. Programmiercode im Allgemeinen wird ein wenig übersichtlicher, wenn man die unterschiedlichen Elemente farbig hervorhebt. Falls man im [[http://forum.onlineforschung.org/|Support-Forum]] postet, sollte man daher dafür sorgen, dass PHP-Code auch als solcher formatiert wird. Dafür gibt es im Forum einen passenden Button.

<code php>
question('AB01');  // Frage AB01
</code>

In dem Beispiel wurde jetzt noch ein sog. Kommentar angehängt (grün). Wenn man zwei Schrägstriche (%%//%%) schreibt, dann ignoriert PHP alles, was danach kommt bis zum Ende der Zeile. Kommentare ändern am PHP-Code also nichts - aber sie sorgen dafür, dass man seinen Quellcode auch nächste Woche noch versteht. Generell machen Kommentare den Code besser leserlich, daher sollte man sie großzügig einsetzen.

===== Variablen =====

Der Begriff //Funktion// kommt aus der Mathematik. Und der Befehl ''question()'' hat mit einer mathematischen Funktion noch herzlich wenig zu tun. Aber Funktionen können auch etwas berechnen oder anderweitig ermitteln. So ermittelt der Befehl ''[[:de:create:functions:casenumber|caseNumber()]]'' zum Beispiel die Nummer des laufenden Interviews (CASE).

<code php>
$num = caseNumber();
</code>

Damit wir mit dem Ergebnis der Funktion (in diesem Fall also mit der Interview-Nummer) etwas machen können, müssen wir sie vorübergehend speichern. Dafür gibt es in den meisten Programmiersprachen Variablen. Variablen kann man sich etwa wie ein leeres Eingabefeld im Fragebogen vorstellen: Man kann etwas hineinschreiben. Nur sieht das zunächst keiner und es wird auch nicht im Datensatz gespeichert.

In PHP beginnen Variablen immer mit einem Dollar-Zeichen (''$''). Im Beispiel oben gibt es eine Variable ''$num''. Wie man seine Variablen nennt, ist Geschmackssache -- nur Umlaute und Sonderzeichen außer dem Unterstrich (''_'') sind weitgehend verboten. Statt ''$num'' könnte man also genauso ''$variable_fuer_fallnummer'' schreiben.

Das Istgleich-Zeichen %%(=)%% ist ein //Operator//. Es sorgt dafür, dass das, was die Funktion ''caseNumber()'' zurückgibt in der Variable ''$num'' links vom Operator gespeichert wird. In der Variable ''$num'' steht nun also die Interview-Nummer.

Wenn wir diese Nummer nun auch noch anzeigen möchten, benötigen wir den Befehl ''[[:de:create:functions:html|html()]]''. Diese Funktion macht nichts anderes, als HTML-Code (also z.B. Text) in den Fragebogen zu schreiben.

<code php>
$num = caseNumber();
$text = (string)$num; // Die Zahl in einen Text umwandeln und in $text speichern
html($text);  // Schreibt den Inhalt von $text in den Fragebogen
</code>

**Hinweis:** Falls Sie sich über die Umwandlung der Zahl in einen Text wundern: Sie könnten auch ''html($zahl)'' schreiben -- und es würde auch funktionieren. Aber SoSci Survey wäre irritiert, warum Sie im Befehl ''html()'' keinen Text (String) verwenden, und würde Sie mit einer Fehlermeldung auf den vermeintlichen Missstand aufmerksam machen.

Legt man in einem Fragebogen einen PHP-Code als Element an und fügt die obigen drei Zeilen ein, so erhält man ein wenig spektakuläres Ergebnis: Bei jedem Aufruf des Fragebogens wird eine stetig steigende Zahl angezeigt.

{{:de:create:scr.php.random.png?nolink|Anzeige einer Zahl im Fragebogen}}

Den Befehl ''caseNumber()'' werden Sie vermutlich nicht häufig benötigen. Für den Moment geht es vorrangig um Variablen: In diese kann man Werte zwischenspeichern und an anderer Stelle wieder verwenden.

===== Texte aneinanderhängen =====

Falls man die Zahl etwas prominenter anzeigen möchte, muss man ein wenig HTML-Code außen herum schreiben. Dazu verkettet man einfach HTML-Code (das ist ja auch nur ein Text, also ein String) mit der Zahl.

Der Operator zum Verknüpfen von Texten (Strings) in PHP ist der Punkt (.). Wenn Sie Strings (Texte) mit Zahlen verknüpfen, so wandelt PHP die Zahl automatisch in einen String um.

Den verknüpften String sollten wir natürlich auch wieder in einer Variable speichern:

**PHP-Code**
<code php>
$zahl = random(1,6);  // Würfelt eine Zahl zwischen 1 und 6
$html = '<h1>Zufallszahl '.$zahl.'</h1>';  // Verkettet 2 Strings und eine Zahl (die automatisch in einen String umgewandelt wird, damit die Verkettung funktioniert)
html($html);  // Schreibt den HTML-Code in den Fragebogen
</code>

In der Variable ''$html'' ist nun z.B. der Text %%"<h1>Zufallszahl 4</h1>"%% gespeichert - wird das HTML im Browser angezeigt, sieht es so aus ([[texts|Texte im Fragebogen]]):

{{:de:create:scr.php.random-h1.png?nolink|Formatierten Text ausgeben}}

**Tipp:** Weitere Erklärungen zur Verwendung finden Sie bei der Referenz zur Funktion ''[[:de:create:functions:html|html()]]''.

===== Referenz für Funktionen =====

Es ist natürlich schön, wenn man mit ''html()'' Text in den Fragebogen schreiben kann oder mit ''question()'' eine Frage anzeigen. Aber woher soll man wissen, welche Funktion was macht und welche Parameter sie erwartet?

Dafür gibt es Referenzen. Für SoSci Survey ist einmal die Liste der speziellen Fragebogen-Funktionen relevant ([[:de:create:functions|PHP-Funktionen]]) und einmal die generelle PHP-Referenz ([[https://php.net/manual/de/index.php|PHP Manual]]). Letztere allerdings eher bei fortgeschrittenen Ansprüchen, zumal SoSci Survey aus Sicherheitsgründen nur eine Auswahl von Befehlen erlaubt (diese sind ebenfalls bei den [[functions|PHP-Funktionen]] aufgelistet).

===== Anwendungen für PHP-Code =====

Die häufigste Anwendung für PHP-Code im Fragebogen sind Filter. Diese werden im Kapitel [[filters|Filterfragen und Filter]] erklärt.

Auch bietet SoSci Survey verschiedene Arten von Variablen, diese werden beschrieben in [[variables|Variablen in SoSci Survey]].

Hohe Flexibilität bieten [[placeholders|Platzhalter]], s. auch [[inputs-single|Eingabefelder frei platzieren]].

Und last but not least kann man in PHP sehr komfortabel mit so genannten Arrays arbeiten - zum Beispiel, um in einer Frage nur jene Items anzuzeigen, die in einer vorhergehenden Frage angekreuzt wurden: [[filter-items|Items in eine anderen Frage übernehmen]].

===== Richtig programmieren =====

Die Anleitungen hier können nur einen ersten Einstieg geben. Wer spannende Algorithmen im Fragebogen verwenden will, der findet hier einen breiteren Einstieg in die Programmiersprache PHP:

  * "PHP für dich" (sehr einfaches Tutorial) auf [[http://www.schattenbaum.net/php/anfang.php|Schattenbaum.net]]
  * "PHP-Einfühung" auf [[http://www.php-einfach.de/php-tutorial/php-tutorial.php|http://www.php-einfach.de]]
  * "quakenet:#php Tutorial" auf [[http://tut.php-quake.net/de/|Quakenet/#php Tutorial]]

**Hinweis:** In den Tutorials steht viel mehr als Sie für die Programmierung des Fragebogens benötigen. Relevant ist vor allem das, was in den Anleitungen zwischen ''**%%<?PHP%%**'' und ''**%%?>%%**'' steht!

**Hinweis:** Um die Sicherheit der Daten und stabile Befragungen zu gewährleisten, sind in SoSci Survey nur bestimmte Funktionen erlaubt. So können Sie z.B. keinen Text mit ''echo'' ausgeben. Statt ''echo'' können sie die Funktion ''[[:de:create:functions:html|html()]]'' verwenden. Sobald Sie eine "verbotene" Funktion im PHP-Code verwenden, erscheint eine entsprechende Warnung und der PHP-Code wird nicht mehr ausgeführt.