====== JavaScript in the Questionnaire ======

PHP code (e.g. for filters) will only be executed when the participant submits a page in the questionnaire to the server after clicking on the Next button, which creates a new page. 

[[:en:glossary#javascript|JavaScript]] is required if the questionnaire should respond immediately when the participant clicks on a button or to user input ([[:en:create:dynamic|Immediately Show Questions when a Certain Option is Selected]]). JavaScript is executed directly in the participant's browser (as long as JavaScript has not been disabled,) and can respond to user input instantly. However, the user cannot access (or only has limited access to) the current questionnaire (e.g. participant's previous responses) with JavaScript.

The JavaScript library ''[[:en:create:soscitools|SoSciTools]]'' is available within the questionnaire. This provides useful functions that make it easier to work with questionnaire content. You can also use the PHP command ''[[:de:create:functions:library|library()]]'' to include standard libraries like jQuery, SCEditor or (if available on the server) highcharts.


===== Tips =====

**Note:** Some question types in SoSci Survey use JavaScript regularly in their display, e.g. rankings, sliders, free mentions, or reaction times measurements.

**Note:** JavaScript cannot be mastered in an afternoon. Several examples of JavaScript are demonstrated in this manual which can be used directly in the questionnaire -- JavaScript can be extremely challenging when going beyond these examples.

**Note:** Using JavaScript can harm the questionnaire's accessibility. People using a screenreader to fill in the questionnaire should keep in mind that the keyboard can be used to fill it in.

**Tip:** If a JavaScript function does not work, the user has to rely on the browser's error console. Potential mistakes in the script can only be seen once the error console is opened. 

**Tip:** If you want to program your own JavaScript, please ensure the questionnaire can still be filled in even if JavaScript has been disabled. 


===== Inserting JavaScript =====

Create a new text element in **Text Elements and Labels** in order to use JavaScript on a page in the questionnaire. This element will contain HTML code and the actual JavaScript code between the ''<script>'' tags within this.  

<code javascript>
<script type="text/javascript">
<!--

// Here is the actual JavaScript,
// i.e. functions and function calls
alert("This is a JavaScript notification");

// -->
</script></code>

**Important:** Select the option "HTML code" in the //Formatting// dropdown.

{{:en:create:scr.javascript.layout.png?nolink|Text with HTML or JavaScript content}}

In **Compose Questionnaire**, the text element is dragged & dropped onto one, or multiple pages, in the questionnaire, or the PHP function ''[[:en:create:functions:text|text()]]'' can also be used.

**Note:** JavaScript can only access HTML elements (e.g. questions) that have already been loaded in the HTML page. It therefore makes sense to put JavaScript at the end of the page.  

**Tip:** In principle, HTML/JavaScript code can also be inserted directly into an HTML element of the questionnaire page. However, text elements offer several advantages, which is why inserting the code directly is not recommended.



===== Examples =====

A few examples of using JavaScript in the questionnaire can be found in the following chapters in the manual:

  * [[:en:create:timer-submit|Timer: Automatically Forward to Next Page]]
  * [[:en:create:timer-display|Timer: Show the 'Next' Button After a Certain Period of Time]]
  * [[:en:create:dynamic|Immediately Show Questions when a Certain Option is Selected]]
  * [[:en:create:break-counter|Record Changes of Browser Window]]


===== Troubleshooting =====

If the JavaScript code does not work as it should, there is the browser's error console for debugging. These can be found -- depending on the browser -- in different places ([[http://webmasters.stackexchange.com/a/77337/30902|Stackexchange: Shortcuts]], [[https://codex.wordpress.org/Using_Your_Browser_to_Diagnose_JavaScript_Errors#Step_3:_Diagnosis|Wordpress: Diagnosis]], [[http://www.stramaxon.com/2013/10/developer-tools-in-browser.html|How to Open Developer Tools]]).

In the error console you can see errors that occured while running the code. You can also display what is stored in a JavaScript variable by using `console. log ()`. The following lines identify an input field with the HTML ID "AB01_01" and then use the console to display whether it was found.

<code javascript>
<script type="text/javascript">
<!--
var input = document.getElementById("AB01_01");
console.log(input);
// -->
</script>
</code>


===== Learn JavaScript =====

There are a number of good introductions to JavaScript on the internet. However, basic programming knowledge is needed beforehand.

[[http://de.selfhtml.org/javascript/index.htm|SelfHTML]] is a website that combines a solid introduction with an extensive compendium [[http://de.selfhtml.org/javascript/index.htm|SelfHTML]] (German only).
