JavaScript-Bibliothek SoSciTools

SoSci Survey bindet im Fragebogen automatisch eine JavaScript-Bibliothek SoSciTools ein. Diese kann in JavaScripts innerhalb des Fragebogens verwendet werden.

Folgende statische Methoden stehen durch SoSciTools zur Verfügung:

• SoSciTools.getForm() – Liefert das HTML-Formularelement <form> des Fragebogens.
• SoSciTools.disableInputs() – Deaktiviert alle Eingabe- und Auswahlfelder auf der aktuellen Fragebogen-Seite (z.B. um Fragen nochmals anzuzeigen ohne dass der Teilnehmer noch etwas ändert, s. auch answers())
• SoSciTools.disableInputs2() – Ersetzt alle Eingabe- und Auswahlfelder durch Grafiken oder Textelemente.

• SoSciTools.questionnaire – Instanz von SoSciTools.Questionnaire zu Steuerung der Fragebogen-Seite
• SoSciTools.progress – Instanz von SoSciTools.Progress zur Steuerung des Fortschrittsbalkens

• SoSciTools.submitPage() – Die Antworten der aktuellen Seite übermitteln, so als würde der Weiter-Knopf gedrückt. Mit dem Parameter "back" kann auch der Zurück-Knopf aktiviert werden (falls auf der Seite vorhanden), mit "repeat" werden die Antworten übermittelt und die Seite dann wiederholt.

• SoSciTools.submitButtonsHide() – Weiter- und Zurück-Knopf ausblenden
• SoSciTools.submitButtonsDisplay() – Weiter- und Zurück-Knopf einblenden
• SoSciTools.showButtons() – Anzeige von Weiter- und Zurück-Knopf bzw. weiteren Knöpfen (Sprachumschalter, Interview abbrechen, Interview unterbrechen) steuern
• SoSciTools.submitButtonEnable() – Den Weiter-Knopf aktiv oder inaktiv (disabled) schalten

• SoSciTools.attachEvent() – Weist einem oder mehreren JavaScript-Ereignissen (Events) eine Funktion zu (browserübergreifend)
• SoSciTools.attachEventToForm() – Weist jeglicher Änderung innerhalb der Fragebogen-Seite eine Funktion zu (browserübergreifend)
• SoSciTools.detachEvent() – Löst eine vorher zugewiesene Funktion von einem JavaScript-Ereignis (browserübergreifend)
• SoSciTools.dispatchEvent() – Löst ein JavaScript-Ereignis aus (browserübergreifend)
• SoSciTools.findContainer(node, containerName, containerClass, alternativeClass) – sucht einen Container zu einem Element
• SoSciTools.getSender() – Ermittelt das Ursprungsobjekt eines JavaScript-Ereignisses (browserübergreifend)
• SoSciTools.inArray() – Prüft, ob ein Element in einem Array enthalten ist (browserübergreifend)
• SoSciTools.recordTime() – zeichnet die Bearbeitungszeit in einer interne Variable auf, siehe auch LatencyTimer.
• SoSciTools.dynamicRows() – blendet die Eingabefelder einer Texteingabe-Frage nach Bedarf ein

Die Variable SoSciTools.questionnaire beherbergt ein Objekt der Klasse SoSciTools.Questionnaire. Das Objekt SoSciTools.questionnaire ist auch unter dem Alias s2 verfügbar (window.s2).

Das Objekt unterstützt folgende Methoden:

• attachCheck() – Registriert eine Funktion zur Prüfung der Eingabe. Die Funktion wird aufgerufen, wenn der Teilnehmer den Weiter-Knopf verwendet.
• submit() – Die Antworten der aktuellen Seite übermitteln, so als würde der Weiter-Knopf gedrückt.

Darüber hinaus werden die (meisten) Fragen auf der Fragebogen-Seite durch ein JavaScript-Objekt innerhalb von s2 repräsentiert. Dieses ist unter der Kennung der Frage verfügbar. Eine Auswahlfrage mit der Kennung SE01 ist etwa unter s2.SE01 verfügbar. Es handelt sich dabei um ein Objekt der Klasse SoSciTools.Question.

(Die meisten) Fragen werden durch ein Objekt der Klasse SoSciTools.Question repräsentiert. Dieses Objekt hat die folgenden Eigenschaften:

• label (lesen) – Liefert die Kennung der Frage
• type (lesen) – Liefert eine Kennung für den Fragetyp
• node (lesen) – Liefert das HTML-Element, welches die Frage repräsentiert, normalerweise entspricht das dem Element mit der HTML-ID [Frage-Kennung]_qst.

Darüber hinaus ist die folgende Methode verfügbar:

• addEventListener() – Listener werden dabei direkt für das HTML-Element der Frage registriert. Der Aufruf s2.AB01.addEventListener() ist äquivalent zu document.getElementById(„AB01_qst“).addEventListener().

Einige Fragetypen (z.B. die Auswahl) lösen ein Ereignis 'response' aus, wenn die Befragten mit der Frage interaktivieren. Das Ereignis (CustomEvent) hat die folgenden Eigenschaften:

• detail.question – {string} Kennung der Frage
• detail.element – {int} Nummer der Option, des Items oder der Teilfrage
• detail.complete – {boolean} Kann die Frage als vollständig beantwortet betrachtet werden
• detail.optional – {int} Wie viele optionale Antworten (z.B. offene Eingabefelder zu den gewählten Optionen) können/sollten ausgefüllt werden? Eine Frage kann vollständig beantwortet sei (z.B. Auswahl einer Option und Eingabe eines Zeichens im offenen Eingabefeld) und dennoch auf weitere Antworten (weitere Zeichen im Eingabefeld) warten.

Die Variable SoSciTools.progress enthält ein Objekt der Klasse SoSciTools.Progress und unterstützt die folgenden Methoden:

• addEventListener() – Registriert eine Funktion für die Ereignisse 'present' oder 'change'.
• set() – Ändert den angezeigten Prozentwert. Anders als die PHP-Funktion option('progress', ...) hat dies keinen Einfluss auf den Prozentwert, der auf der nachfolgenden Seite angezeigt wird.
• setWithinPage() – Ändert den angezeigte Wert anteilig innerhalb der aktuellen Seite, wobei angenommen wird, dass der Fortschrittsbalken auf der folgenden Seite anteilig der Seitenzahl im Gesamtfragebogen steigt.
• setPageMaximum() – Ändert den Wert, mit welchem setWithinPage() arbeitet. Diese JavaScript-Funktion hat genauso wie set() keinen Einfluss darauf, welchen Fortschrittswert die nächste Seite anzeigen wird.