====== Eigene Formularelemente verwenden ======

SoSci Survey bietet zwar eine große Auswahl von [[:de:create:questions|Fragetypen]] -- mitunter ist das aber nicht ausreichend, um eine konkret erforderliche Darstellung für eine Frage zu realisieren. Für diesen Fall kann SoSci Survey auch benutzerdefinierter (HTML-)Formularelemente einlesen. Auch auf JavaScript oder Flash basierende Fragen lassen sich damit einbinden.

Mit diesem Werkzeug erhält man sehr viel Freiheit bei der Gestaltung des Fragebogens -- der Aufwand zum Programmieren der Formularelemente kann allerdings schnell ausarten.

**Tipp:** Bevor Sie mit der Programmierung eigener Formulare beginnen, prüfen Sie bitte einfachere Möglichkeiten unter [[:de:create:composition|Erweiterte Darstellungsmöglichkeiten]].


===== Problemstellung =====

HTML-Formularelemente (z.B. Texteingabefelder, Auswahlfelder, Dropdowns) sind schnell programmiert, die notwendigen Grundlagen sind z.B. auf [[http://de.selfhtml.org/html/formulare/index.htm|SelfHTML]] nachzulesen. Die Einbindung des HTML-Codes in den Fragebogen via Textbaustein ist trivial (HTML-Code als Textbaustein speichern und in den Fragebogen ziehen). 

Das Problem liegt darin, dass SoSci Survey zunächst einmal nichts von den Formularelementen und den von ihnen übermittelten Daten weiß und die Antworten daher nicht speichert. Es liegt also nahe, SoSci Survey mitzuteilen, dass man bestimmte POST-Variablen gerne einlesen und im Datensatz speichern möchte. Dazu verwendet man [[de:create:inputs-single|frei platzierte Eingabefelder]].


===== Umsetzung =====

  * Legen Sie zunächst im **Fragenkatalog** eine Frage vom Typ //[[:de:create:questions:internal|Interne Variablen]]// an.
  * In dieser Frage legen Sie nun mindestens eine Variable (Item) an. Es ist sinnvoll, der Variable eine Beschriftung zu geben: Diese taucht im Fragebogen nicht auf, wohl aber im Datensatz. Wenn Sie mehrere Formularelemente verwenden oder Ihr Formularelement mehrere Variablen speichern soll, legen Sie entsprechend mehrere Variablen (Items) an.
  * Legen Sie nun unter **Textbausteine u. Beschriftung** einen neuen Textbaustein an. Sie können den HTML-Code für das Formularelement zwar prinzipiell auch direkt in den Fragebogen einbinden, aber Textbausteine bieten einige Vorteile.
  * Den HTML-Code für Ihr(e) Formularelement(e) dürfen Sie natürlich selbst programmieren. Unten finden Sie ein Beispiel für ein Dropdown-Auswahlfeld. Wichtig ist nur, dass Sie als Name(n) (Attribut ''name'') des Formularelements die Item-Kennung(en) der internen Variable(n) verwenden. Wenn Ihre Variable also die Kennung "AB01_01" hat, dann steht im Formularelement ''%%name="AB01_01"%%''.
  * Denken Sie bitte auch an die Platzierung des Eingabefelds, z.B. in einer Tabelle.
  * Fügen Sie im Fragebogen (**Fragebogen zusammenstellen**) nun auf der entsprechenden Seite //PHP-Code// ein und verwenden Sie den Befehl ''prepare_input()'', um die interne Variable zu aktivieren, z.B. ''prepare_input('AB01_01');''. Wenn Sie die Kennung der Frage angeben (z.B. ''prepare_input('AB01');''), werden alle Variablen der Frage aktiviert.
  * Fügen Sie den Textbaustein mit dem HTML-Code für das Formularelement ebenfalls auf der Seite ein -- am einfachsten, indem Sie den Textbaustein in die Seite hineinziehen.
  * Starten Sie die Seite nun im Debug-Modus (gelber Pfeil {{:button.debug.here.gif?nolink|Start im Debug-Modus}}). Wenn alles funktioniert hat, dann sehen Sie einen Hinweis, dass Sie die Kennung für ein Formularelement verwenden können sowie Ihr Fomularelement. Der Hinweis dient nur der Orientierung und ist für Teilnehmer später nicht sichtbar.
  * Geben Sie nun einen Wert in Ihr Formularelement ein und klicken Sie auf "Weiter". Wenn Sie nun auf die Debug-Information (die gelbe Ecke rechts oben) klicken, dann sollte dort notiert sein, dass der gewählte/eingegebene Wert abgespeichert wurde.

Wenn Sie anspruchsvollere Eingabeelemente programmieren -- z.B. mit JavaScript und/oder Flash -- dann benötigen Sie in aller Regel versteckte Eingabefelder zum Ablegen der gemessenen/erhobenen Werte (s. [[:de:create:break-counter|Wechsel des Browserfensters aufzeichnen]]).

In diesem Fall versenden Sie __nicht__ die PHP-Funktion ''prepare_input()'', sondern ziehen die Frage vom Typ "interne Variablen" direkt in die Fragebogen-Seite (s. unten). Dies erzeugt automatisch versteckte Eingabefelder im Fragebogen (''%%<input type="hidden">%%''), deren Wert mittels JavaScript geändert werden kann. Die HTML-ID der Eingabefelder entspricht der Item-Kennung.


===== Einschränkungen =====

Bei der Verwendung benutzerdefinierter Formularelemente gibt es zwei wesentliche Einschränkungen:

  - Die Bedeutung der Antwortcodes wird nicht im Datensatz gespeichert. Während bei einer gewöhnlichen Auswahl-Frage z.B. hinterlegt sein könnte, dass Code 1 für "Student" und Code 2 für "Angestellter" steht, müssen Sie das bei einem benutzerdefiniertem Formularelement selbst im Auge behalten.
  - Eine Antwortpflicht muss ggf. über eine [[:de:create:checks#individuelle_antwort-pruefung|Individuelle Antwortprüfung]] realisiert werden. 
  - Wenn Sie dem Teilnehmer einen Zurück-Knopf anbieten oder wenn die Seite bei unvollständigen Angaben wiederholt wird, müssen Sie sich darum kümmern, dass Ihr Formularelement eine vorher gegebene Antwort anzeigt. Dazu können Sie den Wert mittels ''[[:de:create:functions:value|value()]]'' auslesen und mittels Platzhalter in den HTML-Code für die Frage einbinden.


===== Beispiel: Umfangreiche Dropdown-Auswahlfrage =====

SoSci Survey erlaubt in einer normalen Auswahlfrage maximal 99 Optionen. Das gilt auch für die Auswahloptionen in einem Dropdown-Feld. Für eine Liste aller [[http://de.wikipedia.org/wiki/Liste_der_Staaten_der_Erde|Länder der Erde]] reicht das nicht. Ein entsprechendes Auswahlfeld kann man mit folgendem HTML-Code erstellen.

**Tipp:** Eine Dropdown-Auswahl mit mehr als 99 Optionen können Sie auch mit dem Fragetyp [[:de:create:questions:extselect|Erweiterte Auswahl]] erstellen. Eine bestehende Auswahlfrage können Sie im Karteireiter //Erweitert// in eine erweiterte Auswahl umwandeln.

<code html>
<select name="AB01_01">
<option value="1">Abchasien</option>
<option value="2">Afghanistan</option>
<option value="3">Ägypten</option>
<!-- u.s.w. -->
<option value="206">Zypern</option>
</select>
</code>

**Tipp:** Wenn Sie die Auswahloptionen in Excel oder OpenOffice Calc vorliegen haben, dann können Sie mit der Funktion ''VERKETTEN()'' den Großteil des HTML-Codes automatisiert erstellen. Wenn z.B. in der Spalte A die Antwortcodes stehen und in Spalte B die Texte, geben Sie in Spalte C (erste Zeile) folgende Formel ein. Die Formel anschließend über die ganze Spalte C ziehen und den so erstellen Code einfach kopieren.

<code excel>
=VERKETTEN("<option value=""";A1;""">";B1;"</option>")
</code>

Als Name für das Formularelement ''select'' wurde hier ''AB01_01'' eingetragen -- das muss natürlich der tatsächlichen Item-Kennung (des Items in der Frage "interne Variablen") angepasst werden. Bei jeder Auswahloption ''option'' ist ein Attribute ''value'' angegeben -- dieses legt fest, welcher Zahlencode übermittelt wird. Wenn man den tatsächlichen Text abspeichern will, kann man das Attribut einfach weglassen.


==== Aktivierung der internen Variable ====

Fehlt nur noch der entsprechende PHP-Code -- auch hier muss die Kennung angepasst werden:

<code php>
prepare_input('AB01_01');
</code>

Fertig. Zumindest fast.


==== Darstellung im Fragebogen ====

Im Moment würde das Dropdown einfach nur links auf der Seite "kleben". Folgende Tabelle sorgt für etwas mehr Stil:

<code html>
<table cellspacing="0" cellpadding="0" border="0">
<colgroup>
  <col width="100">
  <col>
</colgroup>
<tr>
  <td>
    <label for="AB01_01">Heimatland:</label>
  </td>
  <td>
    <select name="AB01_01" id="AB01_01">
    <option value="1">Abchasien</option>
    <option value="2">Afghanistan</option>
    <option value="3">Ägypten</option>
    <!-- u.s.w. -->
    <option value="206">Zypern</option>
    </select>
  </td>
</tr>
</table>
</code>

Um im Stil der Dropdown-Felder von SoSci Survey zu bleiben, kann man auch die CSS-Klassen aus SoSci Survey verwenden:

<code html>
<div class="spacing">
<div class="title">
<p>Hier steht der Frage-Text</p>
</div>
<div class="titleSpacing"></div>

<table class="question" cellspacing="0" cellpadding="0" width="100%" border="0">
<colgroup>
  <col width="380">
  <col>
</colgroup>

<tr class="shadeH0">
  <td><label for="AB01_01">Heimatland:</label></td>
  <td class="dropdown input">
    <select name="AB01_01" id="AB01_01">
    <option value="1">Abchasien</option>
    <option value="2">Afghanistan</option>
    <option value="3">Ägypten</option>
    <!-- u.s.w. -->
    <option value="206">Zypern</option>
    </select>
  </td>
</tr>
</table>
</div>
</code>

**Tipp:** Welche CSS-Klassen SoSci Survey verwendet, können Sie einfach bei einer "normalen" Fragen nachsehen: Lassen Sie sich auf der entsprechenden Fragebogen-Seite im Browser den HTML-Quellcode anzeigen. Den Quellcode für eine bestimmte Frage finden Sie ganz einfach, indem Sie nach der Frage-Kennung suchen.


===== Beispiel: Verwendung von JavaScript =====

Die oben skizzierte Lösung geht davon aus, dass der Wert aus einem benutzerdefinierten Eingabeelement (''<input>'' oder ''<select>'') in den Datensatz übermittelt werden soll.

Möglicherweise möchten Sie aber gar kein solches Eingabefeld anlegen, sondern einen Wert mittels JavaScript ermitteln und diesen in den Datensatz übertragen. In diesem Fall sind zwei Änderungen notwendig:

  - Entfernen Sie das ''prepare_input()'' aus der Fragebogen-Seite.
  - Ziehen Sie stattdessen die Frage vom Typ "interne Variable" in den Fragebogen und zwar auf die Seite, wo die benutzerdefinierte Frage erscheinen soll. Platzieren Sie die Frage über dem JavaScript, welches den Wert speichern soll.

**Tipp:** Falls Sie nur bestimmte interne Variablen der Frage benötigen, legen Sie dies mit dem {{:button.settings.png?nolink|Einstellungen}}-Symbol fest bei //Items anzeigen//. Alternativ fügen Sie die Frage vom Typ "interne Variablen" mittels PHP-Funktion ''question()'' in die Seite ein und spezifizieren die entsprechenden Item-Kennungen.

Wenn Sie die Frage in den Fragebogen einbinden, sehen Sie optisch keine Veränderung. Allerdings wird für jede interne Variable ein verstecktes Eingabefeld (''%%type="hidden"%%'') hinterlegt, dessen Inhalt per JavaScript gelesen und geändert werden kann.

<code php>
// Variablen 1 und 2 der Frage AB01 (Typ "interne Variablen") einbinden
question('AB01', '1,2');
</code>

<code html>
<script type="text/javascript">
<!--
// Wert in Variable 1 speichern
document.getElementById("AB01_01").value = "Wert A";

// Letzten Wert in Variable 2 um 10 erhöhen
var input2 = document.getElementById("AB01_02");
var curVal = parseInt(input2.value);
if (isNaN(curVal)) {
  input2.value = 10;
} else {
  input2.value = curVal + 10;
}
// -->
</script>
</code>