====== Platzhalter ======

SoSci Survey bietet die Möglichkeit, Inhalte (z.B. Frage- oder Item-Texte) variabel zu gestalten. Dazu werden Platzhalter in der Form ''%platzhalter%'' verwendet. Für den Platzhalter wird dann im Fragebogen etwas eingesetzt -- beispielsweise die Antwort des Befragten auf eine vorhergehende Frage, ein zufällig randomisierter Inhalt/Stimulus oder das Ergebnis einer live-Auswertung.

Es gibt drei Typen von Platzhaltern:

  * Vordefinierte Platzhalter,
  * benutzerdefinierte Platzhalter und
  * Platzhalter für Eingabefelder.

**Tipp:** Platzhalter funktionieren in nahezu allen Texten, von der Frage selbst über Items, Textbausteine, HTML-Code Elemente u.s.w.

**Tipp:** Wenn ein benutzerdefinierter Platzhalter mit [[:de:create:functions:replace|replace()]] einmal vorbereitet wurde, kann er auf allen nachfolgenden Seiten im Fragebogen verwendet werden.

===== Kurzfassung =====

Wenn Sie das folgende Beispiel als Textbaustein im Fragebogen verwenden, wird z.B. die fortlaufende Nummer des Interviews (vordefinierter Platzhalter ''%caseNumber%'') angezeigt.

<code>
Ihr Fragebogen hat die Nummer %caseNumber%.
Bitte notieren Sie diese Nummer, wenn Sie eine Auswertung Ihrer Angaben wünschen.
</code>

Benutzerdefinierte Platzhalter werden mit der Funktion [[:de:create:functions:replace|replace()]] vorbereitet.

<code php>
replace('%fahrzeug%', 'AB01', 'response');  // Antwort aus AB01 in Platzhalter %fahrzeug% ablegen
</code>

<code>
Sie haben vorhin angegeben, meist mit dem %fahrzeug% in die Arbeit zu fahren.
</code>

Darüber hinaus gibt es einige vordefinierte Platzhalter (s. unten) und die Möglichkeit, Eingabefelder (von anderen Fragen) mittels Platzhaltern [[:de:create:inputs-single|frei zu platzieren]].


===== Platzhalter und Filter =====

Das folgende Beispiel zeigt, wie sich Platzhalter mit Filterfragen kombinieren lassen.

In der Frage ''SD01'' wird das Geschlecht des Teilnehmers abgefragt. In weiteren Fragen soll nun erhoben werden, wie der Teilnehmer auf Personen des anderen Geschlecht reagiert. Dafür wird ein Platzhalter ''%person%'' vorbereitet, der im Fragebogen entweder durch "ein Mann" oder "eine Frau" ersetzt wird. Ein zweiter Platzhalter ''%personen%'' wird mit der Plural-Form vorbereitet.

Der folgende PHP-Code wird auf der Seite __nach__ Frage ''SD01'' platziert.

<code php>
if (value('SD01') == 1) {
  // Befragter ist eine Frau
  replace('%person%', 'ein Mann');
  replace('%personen%', 'Männer');
} elseif (value('DC02') == 2) {
  replace('%person%', 'eine Frau');
  replace('%personen%', 'Frauen');
}
</code>

Nun können in weiteren Fragen (auch schon auf derselben Seite, unter dem PHP-Code) die Platzhalter ''%person%'' und ''%personen%'' verwendet werden:

<code>
Welches sind die wichtigsten Eigenschaften, die %person% mitbringen muss, um eine Führungsrolle einzunehmen.
</code>

<code>
Nun geht es um Ihre Erfahrungen. Was würden Sie sagen, wie agieren %personen% in Konfliktsituationen normalerweise?
</code>


===== Vordefinierte Platzhalter =====

Folgende Platzhalter stehen automatisch zur Verfügung, diese Kennungen dürfen __nicht__ für benutzerdefinierte Platzhalter verwendet werden. Die Inhalte der Platzhalter können auch mittels PHP-Funktion zur weiteren Verwendung abgerufen werden (rechte Spalte).

^Kennung^Beschreibung^Variable im Datensatz^PHP-Funktion^
|''%caseNumber%''|Fortlaufende Nummer des Interviews|CASE|''[[:de:create:functions:casenumber|caseNumber()]]''|
|''%caseSerial%''|Seriennummer des Interviews|SERIAL|''[[:de:create:functions:caseserial|caseSerial()]]''|
|''%caseToken%''|Interne Kennung des Interviews|-|''[[:de:create:functions:casetoken|caseToken()]]''|
|''%reference%''|Referenz, die an den Fragebogen übergeben wurde|REF|''[[:de:create:functions:reference|reference()]]''|
|''%pageNumber.abs%''|Nummer der aktuellen Seite laut **Fragebogen zusammenstellen** (Vorsicht bei der Verwendung von Filterfragen)|||
|''%pageNumber.rel%''|Nummer der aktuellen Seite gezählt seit Beginn des Interviews (nicht kompatibel mit ''[[:de:create:function:gotoquestionnaire]]'', ''[[:de:create:functions:multileveldown]]'' und der Funktion **Erhobene Daten** -> **Ausgefüllten Fragebogen ändern**)|||

Folgende Platzhalter stehen innerhalb von Items bzw. Optionen (z.B. im Item-Text) zur Verfügung. Die Nummerierung hilft u.a. dabei, zufällig rotierte Auswahloptionen fortlaufend zu nummerieren.

^Kennung^Beschreibung^Beispiel^
|''%i.n.%''|Nummer des Items mit nachgestelltem Punkt und Leerzeichen|1. |
|''%i.a)%''|Nummer des Items mit nachgestellter Klammer (kleiner Buchstabe)|a) |
|''%i.num%''|Nummer des Items innerhalb einer Frage (numerisch)|1|
|''%i.num.a%''|Nummer des Items innerhalb einer Frage (kleiner Buchstabe)|a|
|''%i.num.A%''|Nummer des Items innerhalb einer Frage (großer Buchstabe)|A|
|''%i.cnt%''|Anzahl der Items innerhalb der Frage|5|

Folgende Platzhalter stehen in einigen (bisher noch nicht allen) Fehlermeldungen zur Verfügung, die unter **Textbausteine u. Beschriftung** angepasst werden können. Hat die betroffene Frage keine Nummer, wird der Platzhalter leer gelassen (entfernt).

^Kennung^Beschreibung^Beispiel^Beispiel^
|''%q.desc%''|Beschreibung der betroffenen Frage(n)|Frage 1|Fragen 2,3|
|''%(q.desc)%''|Beschreibung in Klammern|(Frage 1)|(Fragen 2,3)|
|''%q.list%''|Nummern der betroffenen Frage(n)|1|2,3|

Folgende Platzhalter sind ausschließlich für die Verwendung im HTML-Template eines Layouts vorgesehen. Weitere Platzhalter für das Layout sind unter [[:de:create:layout#vollstaendige_anpassung|Fragebogen-Layouts: Vollständige Anpassung]] dokumentiert.

^Kennung^Beschreibung^
|''%logo%''|HTML-Code für das aktive Logo|
|''%imprint%''|HTML-Code für das Impressum|
|''%progress%''|HTML-Code für den Fortschrittsbalken|
|''%head%''|HTML-Code für den Kopfbereich im Layout-Template|
|''%questionnaire%''|HTML-Code für den Inhalte im Layout-Template|


===== Regeln für benutzerdefinierte Platzhalter =====

Wenn Sie benutzerdefinierte Platzhalter verwenden, beachten Sie für deren Kennung bitte die folgenden Formalia:

  * Nach dem öffnenden Prozent-Zeichen (''%'') muss direkt ein Buchstabe folgen (kein Leerzeichen, keine Ziffer).
  * Vor dem schließenden Prozent-Zeichen darf kein Leerzeichen stehen.
  * Zwischen den beiden Prozent-Zeichen (''%...%'') darf kein weiteres Prozent-Zeichen stehen.
  * Die Platzhalter-Kennung zwischen den Prozent-Zeichen
    * muss mindestens 3 Zeichen lang sein (''%plz%'') und
    * darf maximal 64 Zeichen lang sein.
  * Für den Platzhalter sind die Buchstaben A bis Z (groß oder klein), Zahlen, Punkt, Unterstrich und Leerzeichen erlaubt, aber __keine__ Umlaute.
  * Bei Platzhaltern wird streng zwischen Groß- und Kleinbuchstaben unterschieden: ''%person%'' ist ein anderer Platzhalter als ''%Person%''.


===== Platzierung von Platzhaltern =====

Bei folgenden Beispielen ist in Klammern jeweils die Kennung des Platzhalters angegeben:

  * Ich finde %marke% gut ("marke")
  * %automarke% sieht billig aus ("automarke")
  * Mit dem Produkt %Marke des Produkts% verbinde ich... ("Marke des Produkts")
  * Wort%teile% können genauso ersetzt werden ("teile")


===== Experimentelle Variation =====

Eine effiziente Verwendung von Platzhaltern setzt Grundkenntnisse in der Programmierung mit PHP voraus ([[php|PHP-Code]], Umgang mit [[variables|Variablen]]).

Im folgenden Beispiel wird aus einer Urne ([[:de:create:random_urns|Randomisierung mit Urnen]]) eine von drei möglichen Marken gezogen (Code 1, 2 oder 3). Anschließend wird ein Platzhalter verwendet, um die Marke direkt im Text einer Frage zu verwenden.

<code php>
// Hier werden zunächst verschiedene Marken in ein Array gespeichert
$marken = array(
  1 => 'Ammerseebach',
  2 => 'Britentyler',
  3 => 'Changuella'
);
// Eine dieser Marken wird per Zufall ausgewählt
urnDraw('urne', 'IV01');
$code = value('IV01_01');
// Nun wird mit dem Code (1-3) die Bezeichnung der Marke aus dem Array oben ausgelesen
// (man könnte hier auch mit einem Filter arbeiten anstatt mit dem Array)
$marke = $marken[$code];
// Die Bezeichnung der Marke wird nun im Platzhalter %marke% abgelegt
replace('%marke%', $marke);
</code>

Der Fragetext und die Items werden wie folgt angelegt:

<code>
"Bitte beurteilen Sie die folgenden Aussagen zu %marke%!"
Item 1: "Ich finde %marke% besser als oFb"
Item 2: "%marke% wirkt eher künstlich"
</code>

{{scr.placeholders.example.gif?nolink|Beispiel für die Verwendung von Platzhaltern}}


===== Antworten des Teilnehmers verwenden =====

Wenn man die Antwort eines Teilnehmers weiter hinten im Fragebogen aufgreifen will, ist das mit Platzhaltern recht einfach zu bewerkstelligen. Man muss lediglich darauf achten, dass der Fragebogen auch dann noch korrekt funktioniert, wenn der Teilnehmer nichts (oder nur Leerzeichen) antwortet.


==== Texteingabe ====

Voraussetzung für das folgende Beispiel ist, dass in der offenen Texteingabe ''TX01_01'' eine Marke abegfragt wurde. Der folgende PHP-Code darf __nicht__ auf derselben Seite wie Frage ''TX01'' platziert werden, sondern erst auf einer der folgenden Seiten.

<code php>
// Antwort des Teilnehmers auslesen
$marke = value('TX01_01');
// Leerzeichen entfernen
$marke = trim($marke);
// Sinnvoll reagieren, wenn nichts eingegeben wurde
if ($marke == '') {
  goToPage('next'); // Seite überspringen
}
// Platzhalter %marke% vorbereiten
replace('%marke%', $marke);
// Nachfolgende Fragen können nun den Platzhalter %marke% verwenden
</code>

Wenn Item ''TX01_01'' eine Pflichtfrage ist und somit ausgeschlossen werden kann, dass die Antwort fehlt, kann [[:de:create:functions:replace|replace()]] die Antwort auch direkt abrufen:

<code php>
// Platzhalter %marke% vorbereiten
replace('%marke%', 'TX01_01', 'response');
// Nachfolgende Fragen können nun den Platzhalter %marke% verwenden
</code>


==== Auswahlfrage ====

Im folgenden Beispiel soll die Option als Text angezeigt werden, die in einer Auswahl (einfache Auswahl oder Dropdown) gewählt wurde. Voraussetzung ist, dass in der Auswahlfrage ''AU01'' eine Obstsorte ausgewählt wurde.

Der PHP-Code darf wegen des ''value()'' wiederum __nicht__ auf derselben Seite stehen wie die Frage ''AU01'', sondern erst auf einer nachfolgenden Seite.

**Tipp:** Lesen Sie auch die Anleitung zur Funktion ''[[:de:create:functions:value|value()]]''.

<code php>
// Erst einmal prüfen, ob überhaupt etwas ausgewählt wurde
if (value('AU01') < 0) {
  // Seite überspringen
  goToPage('next');
}

// Antwort auslesen - beachten Sie den zweiten Parameter 'text'
$text = value('AU01', 'text');
// Platzhalter %obst% vorbereiten
replace('%obst%', $text);
// Folgende Fragen oder Texte können nun den Platzhalter %obst% verwenden.
</code>

Auch hier kann [[:de:create:functions:replace|replace()]] den Wert direkt abrufen, wenn ''AU01'' eine Pflichtfrage ist und der Filter damit überflüssig wird:

<code php>
// Platzhalter %obst% vorbereiten
replace('%obst%', 'AU01', 'response');
// Folgende Fragen oder Texte können nun den Platzhalter %obst% verwenden.
</code>