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

SoSci Survey automatically includes a JavaScript library ''SoSciTools'' in the questionnaire. It can be used 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()'' -- Submit the answers of the current page as if the Next button was pressed. With the parameter ''%%"back"%%'', the Back button can be activated as well (if present on the page); with ''%%"repeat"%%'', the answers are submitted and the page is then repeated.

==== Buttons in the Questionnaire ====

  * ''SoSciTools.submitButtonsHide()'' -- Hide Next and Back button
  * ''SoSciTools.submitButtonsDisplay()'' -- Show Next and Back button
  * ''[[:en:create:soscitools:showbuttons|SoSciTools.showButtons()]]'' -- Control the display of the Next and Back button or other buttons (language switch, cancel interview, pause interview)
  * ''[[:en:create:soscitools:submitbuttonenable|SoSciTools.submitButtonEnable()]]'' -- Switch the Next button active or inactive (disabled)

==== General Helper 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()]]'' -- Detaches 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 of 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 whether 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#display_lines_one_after_another|SoSciTools.dynamicRows()]]'' -- Displays the input fields of a text input question as required


==== Dynamic Filters ====

  * ''new SoSciTools.ToggleDropdown(input, optionValues, targetIDs)''\\ Shows or hides one or more HTML elements (//targetIDs//), depending on what was selected in the dropdown //input// (HTML ID)
  * ''new SoSciTools.ToggleSelection(selectionID, optionValues, targetIDs)''\\ Shows or hides one or more HTML elements (//targetIDs//), depending on what was selected in the selection question //selectionID// (SoSci question ID).

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

The variable ''SoSciTools.questionnaire'' contains an object of the class ''SoSciTools.Questionnaire''. The object ''SoSciTools.questionnaire'' is also available under the alias ''s2'' (''window.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 answers 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''. It is available under the ID of the question. A selection question with the ID ''SE01'', for example, is available as ''s2.SE01''. This is an object of the class ''SoSciTools.Question''.


===== SoSciTools.Question =====

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

  * ''label'' (read) -- Returns the ID of the question
  * ''type'' (read) -- Returns an identifier for the question type
  * ''node'' (read) -- Returns the HTML element that represents the question; usually, this is the element with the HTML ID ''[question ID]_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 (e.g. the selection) trigger an event ''%%'response'%%'' when respondents interact with the question. The event (''CustomEvent'') has the following properties:

  * ''detail.question'' -- ''{string}'' ID of the question
  * ''detail.element'' -- ''{int}'' Number of the option, item or sub-question
  * ''detail.complete'' -- ''{boolean}'' Can the question be considered as completely answered?
  * ''detail.optional'' -- ''{int}'' How many optional answers (e.g. open input fields for the selected options) can/should be filled in? A question can be completely answered (e.g. 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. Unlike the PHP function ''[[:en:create:functions:option|option('progress', ...)]]'', this does not affect the percentage 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 in proportion to the page number in the overall questionnaire.
  * ''setPageMaximum()'' -- Changes the value that ''setWithinPage()'' works with. Just like ''set()'', this JavaScript function has no influence on which progress value the next page will display.