====== JavaScript-Bibliothek SoSciTools ======

SoSci Survey bindet im Fragebogen automatisch eine JavaScript-Bibliothek ''SoSciTools'' ein. Diese kann in [[:de:create:javascript|JavaScripts]] innerhalb des Fragebogens verwendet werden.

===== SoSciTools =====

Folgende statische Methoden stehen durch SoSciTools zur Verfügung:

==== Fragebogen-Elemente ====

  * ''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 [[:de:create:functions:answers]])
  * ''SoSciTools.disableInputs2()'' -- Ersetzt alle Eingabe- und Auswahlfelder durch Grafiken oder Textelemente.

  * ''SoSciTools.questionnaire'' -- Instanz von ''[[#soscitoolsquestionnaire|SoSciTools.Questionnaire]]'' zu Steuerung der Fragebogen-Seite
  * ''SoSciTools.progress'' -- Instanz von ''[[#soscitoolsprogress|SoSciTools.Progress]]'' zur Steuerung des Fortschrittsbalkens


==== Fragebogen-Steuerung ====

  * ''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.

==== Knöpfe im Fragebogen ====

  * ''SoSciTools.submitButtonsHide()'' -- Weiter- und Zurück-Knopf ausblenden
  * ''SoSciTools.submitButtonsDisplay()'' -- Weiter- und Zurück-Knopf einblenden
  * ''[[:de:create:soscitools:showbuttons|SoSciTools.showButtons()]]'' -- Anzeige von Weiter- und Zurück-Knopf bzw. weiteren Knöpfen (Sprachumschalter, Interview abbrechen, Interview unterbrechen) steuern
  * ''[[:de:create:soscitools:submitbuttonenable|SoSciTools.submitButtonEnable()]]'' -- Den Weiter-Knopf aktiv oder inaktiv (disabled) schalten

==== Allgemeine Hilfsfunktionen ====

  * ''[[:de:create:soscitools:attachevent|SoSciTools.attachEvent()]]'' -- Weist einem oder mehreren JavaScript-Ereignissen (Events) eine Funktion zu (browserübergreifend)
  * ''[[:de:create:soscitools:attacheventtoform|SoSciTools.attachEventToForm()]]'' -- Weist jeglicher Änderung innerhalb der Fragebogen-Seite eine Funktion zu (browserübergreifend)
  * ''[[:de:create:soscitools:detachevent|SoSciTools.detachEvent()]]'' -- Löst eine vorher zugewiesene Funktion von einem JavaScript-Ereignis (browserübergreifend)
  * ''[[:de:create:soscitools:dispatchevent|SoSciTools.dispatchEvent()]]'' -- Löst ein JavaScript-Ereignis aus (browserübergreifend)
  * ''[[:de:create:soscitools:findcontainer|SoSciTools.findContainer(node, containerName, containerClass, alternativeClass)]]'' -- sucht einen Container zu einem Element
  * ''[[:de:create:soscitools:getsender|SoSciTools.getSender()]]'' -- Ermittelt das Ursprungsobjekt eines JavaScript-Ereignisses (browserübergreifend)
  * ''[[:de:create:soscitools:inarray|SoSciTools.inArray()]]'' -- Prüft, ob ein Element in einem Array enthalten ist (browserübergreifend)
  * ''[[:de:create:soscitools:recordtime|SoSciTools.recordTime()]]'' -- zeichnet die Bearbeitungszeit in einer interne Variable auf, siehe auch [[:de:create:javascript:latencytimer|LatencyTimer]].
  * ''[[:de:create:questions:text#zeilen_nacheinander_einblenden|SoSciTools.dynamicRows()]]'' -- blendet die Eingabefelder einer Texteingabe-Frage nach Bedarf ein


===== SoSciTools.Questionnaire =====

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:

  * ''[[:de:create:soscitools:questionnaire:attachcheck|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''.


===== 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.


===== SoSciTools.Progress =====

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

  * ''[[:de:create:soscitools:progress:addeventlistener|addEventListener()]]'' -- Registriert eine Funktion für die Ereignisse '''present''' oder '''change'''.
  * ''[[:de:create:soscitools:progress:set|set()]]'' -- Ändert den angezeigten Prozentwert. Anders als die PHP-Funktion ''[[:de:create:functions:option|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.