JavaScript Library SoSciTools

SoSci Survey automatically includes a JavaScript library SoSciTools in the questionnaire. It can be used in JavaScripts within the questionnaire.

The following static methods are available through SoSciTools:

• 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 answers())
• SoSciTools.disableInputs2() – Replaces all input and selection fields with graphics or text elements.

• SoSciTools.questionnaire – Instance of SoSciTools.Questionnaire to control the questionnaire page
• SoSciTools.progress – Instance of SoSciTools.Progress to control the progress bar

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

• SoSciTools.submitButtonsHide() – Hide Next and Back button
• SoSciTools.submitButtonsDisplay() – Show Next and Back button
• SoSciTools.showButtons() – Control the display of the Next and Back button or other buttons (language switch, cancel interview, pause interview)
• SoSciTools.submitButtonEnable() – Switch the Next button active or inactive (disabled)

• SoSciTools.attachEvent() – Assigns a function to one or more JavaScript events (cross-browser)
• SoSciTools.attachEventToForm() – Assigns a function to any change within the questionnaire page (cross-browser)
• SoSciTools.detachEvent() – Detaches a previously assigned function from a JavaScript event (cross-browser)
• SoSciTools.dispatchEvent() – Triggers a JavaScript event (cross-browser)
• SoSciTools.findContainer(node, containerName, containerClass, alternativeClass) – Searches for a container of an element
• SoSciTools.getSender() – Determines the source object of a JavaScript event (cross-browser)
• SoSciTools.inArray() – Checks whether an element is contained in an array (cross-browser)
• SoSciTools.recordTime() – Records the processing time in an internal variable, see also LatencyTimer.
• SoSciTools.dynamicRows() – Displays the input fields of a text input question as required

• 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).

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:

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

(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).

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

• addEventListener() – Registers a function for the events 'present' or 'change'.
• set() – Changes the displayed percentage. Unlike the PHP function 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.