====== JavaScript Library SoSciTools ======

SoSci Survey automatically includes a JavaScript library in the questionnaire . This can be used SoSciTools in [[:en:create:javascript|JavaScripts]] within the questionnaire.

===== SoSciTools =====

The following static methods are available through SoSciTools:

==== Questionnaire Elements ====

  * ''SoSciTools.getForm()'' -- Returns the HTML form element ''<form>'' of the questionnaire.
  * ''SoSciTools.disableInputs()'' -- Deactivates all input and selection fields on the current questionnaire page (e.g. to display questions again without the participant changing anything, see also [[:en:create:functions:answers]])
  * ''SoSciTools.disableInputs2()'' -- Replaces all input and selection fields with graphics or text elements.

  * ''SoSciTools.questionnaire'' -- instance of ''[[#soscitoolsquestionnaire|SoSciTools.Questionnaire]]'' to control the questionnaire page
  * ''SoSciTools.progress'' -- Instance of ''[[#soscitoolsprogress|SoSciTools.Progress]]'' to control the progress bar.


==== Questionnaire Control ====

  * ''SoSciTools.submitPage()'' -- Send the answers from the current page as if the Next button was pressed. The parameter "back"can also be used to activate the Back button (if present on the page), which "repeat"will send the answers and then repeat the page.
==== Buttons in Questionnaires ====

  * ''SoSciTools.submitButtonsHide()'' -- Hide next and back button
  * ''SoSciTools.submitButtonsDisplay()'' -- Show next and back button
  * ''[[:en:create:soscitools:showbuttons|SoSciTools.showButtons()]]'' --Control the display of next and previous buttons or other buttons (language switch, cancel interview, pause interview)
  * ''[[:en:create:soscitools:submitbuttonenable|SoSciTools.submitButtonEnable()]]'' -- Activate or deactivate the Next button
==== General Help Functions ====

  * ''[[:en:create:soscitools:attachevent|SoSciTools.attachEvent()]]'' -- Assigns a function to one or more JavaScript events (cross-browser)
  * ''[[:en:create:soscitools:attacheventtoform|SoSciTools.attachEventToForm()]]'' -- Assigns a function to any change within the questionnaire page (cross-browser)

  * ''[[:en:create:soscitools:detachevent|SoSciTools.detachEvent()]]'' -- De-assigns a previously assigned function from a JavaScript event (cross-browser)
  * ''[[:en:create:soscitools:dispatchevent|SoSciTools.dispatchEvent()]]'' -- Triggers a JavaScript event (cross-browser)
  * ''[[:en:create:soscitools:findcontainer|SoSciTools.findContainer(node, containerName, containerClass, alternativeClass)]]'' -- searches for a container for an element
  * ''[[:en:create:soscitools:getsender|SoSciTools.getSender()]]'' -- Determines the source object of a JavaScript event (cross-browser).
  * ''[[:en:create:soscitools:inarray|SoSciTools.inArray()]]'' -- Checks if an element is contained in an array (cross-browser)
  * ''[[:en:create:soscitools:recordtime|SoSciTools.recordTime()]]'' -- records the processing time in an internal variable, see also [[:en:create:javascript:latencytimer|LatencyTimer]]. 
  * ''[[:en:create:questions:text#show_rows_next|SoSciTools.dynamicRows()]]'' -- displays the input fields of a text input question as required.


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

The variable SoSciTools.questionnairecontains an object of the class SoSciTools.Questionnaire. The object is also available SoSciTools.questionnaireunder the alias ( ). s2window.s2

The object supports the following methods:

  * ''[[:en:create:soscitools:questionnaire:attachcheck|attachCheck()]]'' -- Registers a function to check the input. The function is called when the participant uses the Next button.
  * ''submit()'' -- Submit the responses of the current page, as if the Next button was pressed.


In addition, (most) questions on the questionnaire page are represented by a JavaScript object within s2. This is available under the question identifier . A multiple choice question with the identifier , SE01for example, is available under s2.SE01. It is an object of the class SoSciTools.Question.

===== SoSciTools.Question =====
(Most) questions are SoSciTools.Questionrepresented by an object of the class. This object has the following properties:

  * ''label'' (read) -- Returns the question identifier
  * ''type'' (read) -- Returns an identifier for the question type
  * ''node'' (read) -- Returns the HTML element that represents the question, usually the element with the HTML ID [QuestionID]_qst.

In addition, the following method is available:

  * ''addEventListener()'' -- Listeners are registered directly for the HTML element of the question. The call s2.AB01.addEventListener()is equivalent to document.getElementById(„AB01_qst“).addEventListener().

Some question types (eg choice) trigger an event 'response'when respondents interact with the question. The event (CustomEvent) has the following properties:

  * ''detail.question'' -- ''{string}'' Question identifier
  * ''detail.element'' -- ''{int}'' Number of the option, item or sub-question
  * ''detail.complete'' -- ''boolean}'' Can the question be considered fully answered
  * ''detail.optional'' -- ''{int} '' How many optional answers (eg open input fields for the selected options) can/should be filled in? A question can be fully answered (eg selecting an option and entering a character in the open input field) and still wait for further answers (further characters in the input field).



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

The variable ''SoSciTools.progress'' contains an object of the class ''SoSciTools.Progress'' and supports the following methods:

  * ''[[:en:create:soscitools:progress:addeventlistener|addEventListener()]]'' -- Registers a function for the events '''present''' or '''change'''.
  * ''[[:en:create:soscitools:progress:set|set()]]'' -- Changes the displayed percentage value. Unlike the PHP function ''[[:en:create:functions:option|option('progress', ...)]]'', this does not affect the percentage value displayed on the following page.

  * ''setWithinPage()'' -- Changes the displayed value proportionally within the current page, assuming that the progress bar on the following page increases proportionally to the number of pages in the overall questionnaire.
  * ''setPageMaximum()'' -- Changes the value that setWithinPage()is working with. This JavaScript function has set()no influence on what progress value the next page will display.