====== Record Clicks to an External Website ======

An external website is easily linked using HTML. HTML code can be used practically everywhere in SoSci Survey (i.e. questionnaire, items, text elements with formatting "HTML Code").

<code html>
<a href="https://www.soscisurvey.de/">SoSci Survey Homepage</a>
</code>

Only one additional parameter is necessary to open a link in a new browser window or tab:

<code html>
<a href="https://www.soscisurvey.de/" target="_blank">SoSci Survey Homepage</a>
</code>

In some research designs links are not only useful to inform the participants, but their use is also that of a dependent variable (DV). Therefore, the researcher needs to know whether a link was clicked or not.

This instruction describes two possible solutions:

  * The first solution requires [[:en:create:javascript|JavaScript]] which is activated for most participants.
  * The second solution uses buttons instead of "normal" links. If the respondent whall leave the questionnaire by clicking the link (and does not return), than this solution works even if JavaScript is disabled. 

**Important:** The link cannot be placed on the last page of the questionnaire. If it were, the interview would be finished and no more data could be saved. Instead, you can add an additional page just before the last one, where the content of the last page can be copied. The "Next" button can be hidden using the JavaScript command ''[[:de:create:soscitools|SoSciTools.submitButtonsHide()]]'' oder using the PHP command ''[[:en:create:functions:buttonhide]]'' if you do not want to continue to the last page. However, be careful using ''SoSciTools.submitPage()'', which does not work for the second version (see below).


===== Preparations =====

In both solutions an [[:en:create:questions:internal|internal variable]] is needed to save the presence of the click in the dataset. The following guide assumes that the internal variable uses the label '' IV01_01'' (the associated question uses the label ''IV01''). The interval variable can be placed in any section and use another label. In that case the code example have to be adapted.

It should also be clarified whether the questionnaire remains open in the background (solution using JavaScript) or whether the participant will leave the questionnaire when clicking the link (solution using a button).


===== Record Clicks Using JavaScript =====

To recond the click using JavaScript, you have to trigger a JavaScript event when clicking the link. This event then submits this piece of cata and, if applicable, send it to the survey server.

The link get a unique HTML identifier, in the following example ''"link01"''.

<code html>
<a href="https://www.soscisurvey.de/" id="link01" target="_blank">SoSci Survey Homepage</a>
</code>

The subsequent HTML code binds an anonymous function to the click on the link. This function writes the value ''2'' into the internal variable. In addition, the JavaScript code ensures that the variable gets the value ''1'' if JavaScript is enabled. Above the HTML code, a little PHP code is inserted on the questionnaire page. This preallocates the internal variable with the value -1 (if this is in the data set, JavaScript was deactivated) and integrates it into the questionnaire page.

<code php>
preset('IV01_01', -1);
question('IV01');
</code>

<code javascript>
<!-- Here is the actual link -->
<a href="https://www.soscisurvey.de/" id="link01" target="_blank">SoSci Survey Homepage</a>
<!-- And here the JavaScript for the storage -->
<script type="text/javascript">
<!--
document.getElementById("IV01_01").value = "1";
SoSciTools.attachEvent(document.getElementById("link01"), "click", function() {
  document.getElementById("IV01_01").value = "2";
});
// -->
</script>
</code>

If you now click on the link, the value 2 is first stored in the input field of the internal variable. It is not yet stored in the data set. There are now 3 possibilities for this:

  - In the internal variable's properties (click on the variable in the navigation on the left ), you can change //Transmission// to "Transmit data in background periodically". 
  - You can wait for the participant to return to the questionnaire and click "Next". Depending on the design, this can be risky (no data about the click may be stored if the respondent dies not return).
  - When you click on the link, you can automatically switch to the following page in the questionnaire. For this you have to add the command ''SoSciTools.submitPage()''. However, this does not work in conjunction with the PHP command ''buttonHide()'' mentioned above.

<code javascript>
document.getElementById("IV01_01").value = "1";
SoSciTools.attachEvent(document.getElementById("links01"), "click", function() {
  document.getElementById("IV01_01").value = "2";
  SoSciTools.submitPage();
});
</code>

In principle, JavaScript can also be used to save how often the link was clicked on or how long the participant stayed on the external page before returning to the questionnaire -- whereby you never know whether he or she checked his or her e-mails quickly along the way.


===== Record clicks through a jump to a page =====

This solution requires an additional page in the questionnaire -- one that is not visible in the normal process. By clicking on the link, the participant jumps to an extra page, using the PHP function ''[[:de:create:functions::buttontopage]]''. On the extra page, the click is registered and the participant is redirected to the actual target page.

If the link is already on the "last page" or, more precisely, on an additional farewell page of the questionnaire, it is advisable to leave the questionnaire by clicking on the link.

In principle, it would also be possible to continue the questionnaire after clicking in this constellation. However, opening a new window using JavaScipt, which would be necessary, is blocked by many browsers. Therefore only the reliable solution is shown here where the participant leaves the questionnaire by clicking on the link.

This actually requires 2 preceding pages, and at least one of them requires a [[:en:glossary#seitenkennung|Seitenkennung]], in the example "link01":


  * The preceding farewell side (no page identifier required) with ''buttonToPage()''
  * The page with the redirection and has a page identifier, e.g. "link01"
  * And only then follows the "last page" with the automatically preset identifier "end".

On the preceding farewell page, the button is now integrated using [[:en:create:placeholders|Platzhalter]] or simply using the command ''[[:en:create:functions:html]]'' and the Next button is deactivated.

<code php>
$htmlButton = buttonToPage('link01', 'Info page for SoSci Survey');
html('<p>If you want to learn more about this fantastic software, visit '.$htmlButton.'</p>');

// No normal "Next" button
buttonHide();

// Initialize the internal variable (Code 1)
put('IV01_01', 1);
</code>

Using CSS you can format the button or even give it the appearance of a "normal" link.

On the extra page "link01" the command ''[[:de:create:functions:redirect]]'' now redirects the participant directly to the desired page. And ''[[:de:create:functions:put]]'' stores 

<code php>
put('IV01_01', 2);
redirect('https://www.soscisurvey.de/');
</code>


==== Appearance like a link ====

The following PHP code for the first preceding page (the one with ''buttonToPage()'') uses the placeholder ''%link01%'' instead of a string link, which can be placed not only in ''html()'' but also in any text element.

Furthermore, the fourth parameter in ''buttonToPage()'' assigns a CSS class (here e.g. "likelink") to the button, which is formatted like a "normal" link with a little CSS code. The CSS code is embedded on the page using ''[[:de:create:functions:pagecss|pageCSS()]]''.

<code php>
buttonToPage('link01', 'Info page for SoSci Survey', '%link01%', 'likelink');
html('<p>If you want to learn more about this fantastic software, visit %link01%.</p>');
 
// Formating the button
pageCSS('
button.likelink {
  background-color: transparent;
  border: 0 none;
  padding: 0;
  color: #FF9900;
  text-decoration: underline;
}
');

// No normal "Next" button
buttonHide();
 
// Initialize the internal variable (Code 1)
put('DF07_01', 1);
</code>