====== buttonToPage() ======

''string **buttonToPage**(string //page//, [mixed //annotation//, mixed //placeholder//, mixed //CSS-class//])''

With this function you can create buttons to navigate within the questionaire. The function returns
the HTML-code of the button and saves it (optinal) in a placeholder, e.g. to use it in the [[:en:create:layout|Layout]].


  * //page//\\ questionaire ID to which one leaps by clicking the button.
    * <[[:en:glossary#seitenkennung|Page IDs]]> -- Leap to a specific page.
    * '''end''' -- leap to the last page (end of the survey)
  * //annotation//\\ The annotation of the button (text or HTML-code). If no annotation is added, the button will use the note of the page or the page ID.
    * <string> -- annotation independent of the language version
    * <array> -- annotation depending on language version. The label of the language version (e.g. ''"ger"'' or ''"eng"'') can be used as a key of the array, with the annotation as the actual value of the array.
  * //placeholder//\\ If the third parameter is given a placeholder or ''true'', the button will be valid for the whole questionaire, otherwise just for the current page. 
    * <[[:en:create:placeholders#regeln_fuer_benutzerdefinierte_platzhalter|placeholder]]> -- The HTML-code of the button will be saved in the denoted placeholder and can be used e.g. in the layout. 
    * ''true'' -- The button is valid for the whole questionnaire but has to be integrated manually. 
    * ''null'' or ''false'' -- The button is just valid on the current page of the questionnaire.
  * //CSS-class//\\ The ''<button>''-tag, which is used for the button, could additionally to the CSS-class ''buttonToPage'' have further CSS-classes as arrays or strings. In that way one could implement a hierachical navigation.

**Note:** When leaving a page through a button that was included via ''buttonToPage()'' the answers to mandatory questions will not be checked for completeness.
===== Go back several pages =====

The participant shall have the opportunity to leap to a previous page.

Name the Page ID of the previous page, to which the participant shall leap e.g. "early" ([[:en:glossary#seitenkennung|Page IDs]]).

Add the followin PHP-Code at the place where the button shall appear ([[:en:create:php]])

<code php>
html(
  '<div style="text-align: center; margin: 2em 0">'.
  buttonToPage('early', 'Back to selection').
  '</div>'
);
</code>

The ''<div>''-Tag is used so that the button is shown in its own line and it will also add some space above and below the button.


===== Easy Navigation =====

The participant shall have the option to leap to two specific pages during the whole survey. 

Name the two Page IDs in the quiestionaire e.g. "jump1" and "jump2".

Add the following PHP-Code on the first page of the questionnaire:

<code php>
buttonToPage('jump1', 'To the selection', '%btnJ1%');
buttonToPage('jump2', 'To the overview', '%btnJ2%');
</code>

Add in the HTML-template of the layout ([[:en:create:layout]]) at a convenient position
(e.g. left in the navigation, if it exists in the layout or as a placeholder for the next-button) the following HTML-Code.

<code html>
<div style="margin: 2em 0">
  <div>%btnJ1%</div>
  <div>%btnJ2%</div>
</div>
</code>

**Please note:** The buttons will just be displayed, if the questionnaire is started from the first page on. If you start the questionnaire in order to test it on a later page, you will just see the placeholder.



===== Editing Previous Sections =====

Again we want to offer the participant several buttons in order to navigate within the questionnaire. However this time the participant has the option to leap to chapters of the questionaire that he/she has already completed.

Name the pages, on which a chapter starts with distinct Page IDs e.g. "chapter1" untill "chapter4".

Initiate placeholders with the following PHP-code for all buttons (e.g. "%btnC1%" untill "%btnC5%"). The if-filter with ''[[:en:create:functions:getroute]]'' makes sure, that buttons for chapters that have been reached are kept if the participant reloads the first page.

<code php>
if (getRoute() == 'start') {
  replace('%btnC1%', '');
  replace('%btnC2%', '');
  replace('%btnC3%', '');
  replace('%btnC4%', '');
  replace('%btnC5%', '');
}
</code>

Add on each of the 5 chapter-pages, from where the respective button shall appear the following PHP-Code. The parameters obviously have to be addapted to the equivalent page.

<code php>
buttonToPage('chapter1', 'chapter 1', '%btnC1%');
</code>

Again, in the HTML-template of the layout you will have to add placeholders:

<code html>
<!-- buttons below one each other -->
<div style="margin: 2em 0">
  <div>%btnC1%</div>
  <div>%btnC2%</div>
  <div>%btnC3%</div>
  <div>%btnC4%</div>
  <div>%btnC5%</div>
</div>
<!-- buttons next to each other -->
<div style="margin: 2em 0">
  %btnC1%
  %btnC2%
  %btnC3%
  %btnC4%
  %btnC5%
</div>
</code>

===== Non-linear Questionnaires =====

The questionnaire should not (necessarily) be answered linearly? With ''buttonToPage()'' an extensive navigation can be realized.

In preparation, give all pages on which a section begins a [[:en:glossary#page_ids|Page IDs]] under **Compile questionnaire** and enter as a comment for the page a title for the section as it should appear in the navigation.

There are two ways to display the navigation on all pages:

  - Use placeholders and use them directly in the **questionnaire layout** -> //HTML-template// in front of the placeholder ''%questionnaire%'' -- then the PHP code with ''buttonToPage()'' has to be placed only once on the first page of the questionnaire, but the current page cannot be highlighted in color with this solution.
  - Place the PHP code for navigation on each page of the questionnaire, e.g. at the top of each page. Below is an example of what the PHP code for this might look like:

<code php>
html(
  // A <div> provides the optical demarcation between navigation and page content
  '<div style="border: 2px solid #CCCCCC; border-left: 0 none; border-right: 0 none; padding: 20px 0 12px 0; margin-bottom: 3em;">'.
  // Another <div> allows the flexible arrangement of the navigation buttons
  '<div class="s2flex navButtons" style="flex-wrap: wrap; margin-right: -8px">'.NL.
  buttonToPage('start').
  buttonToPage('contact').
  buttonToPage('study').
  buttonToPage('transcript').
  buttonToPage('dokuments').
  buttonToPage('notes').
  '<div style="width: 2em;"></div>'.
  buttonToPage('send').
  '</div>'.
  '</div>'
);
</code>

If you want to make the buttons a bit more attractive, you can add some CSS code to the **questionnaire layout** in the //HTML-template// at the ''<style>'' section:

<code css>
div.navButtons button {
  border: 2px solid %color.4%;
  border-radius: 5px;
  padding: 7px 6px;
  margin-bottom: 8px;
  flex-grow: 1;
  margin-right: 8px;
}
div.navButtons button.currentPage {
  background-color: %color.4%;
  color: white;
}
</code>


===== Example: Multilingual Annotation =====

In a multilingual questionnaire ([[:en:create:multilang]]) the annotation of each button has to be adapted. In order to do so you can pass an array onto the second parameter.

Initially determine under **languageversion**, the (three-digit) code of the languages that you want to use. The following example uses different annotations  for the language "Deutsch (Sie)", code "ger" and "English", code "eng".

<code php>

<code php>
html(
  '<div style="text-align: center; margin: 2em 0">'.
  buttonToPage('early', array(
    'ger' => 'Zurück zur Auswahl',
    'eng' => 'Back to Selection'
  )).
  '</div>'
);
</code>

The same code also works with placeholder (the three different notations merely demonstrate how you can spread the PHP-code to several lines depending on your preferences).

<code php>
buttonToPage('chapter1', array('ger' => 'Kapitel 1', 'eng' => 'Chapter 1'), '%btnC1%');

buttonToPage('chapter2', array(
  'ger' => 'Kapitel 2',
  'eng' => 'Chapter 2'
), '%btnC2%');

buttonToPage(
  'chapter3',
  array(
    'ger' => 'Kapitel 3',
    'eng' => 'Chapter 3'
  ),
  '%btnC3%'
);
</code>

===== Optional Pages =====
 
Another application of ''buttonToPage()'' is that you can implement optional pages or sections in the questionnaire. For example, [[:en:create:consent|informed consent]] could initially only present a short summary of the information and by clicking on the button "complete information" you get to a page that contains the detailed information. 

In practice, the full information page would be skipped if the respondent just clicked "next". So you would have the following pages: 
 
	* Page 1 containing the summary
	* Page 2 ("details") with detailed information
	* Page 3 ("start") where the actual questionnaire begins

The PHP code would cover the placeholder ''%details%'' with a button to page 2, while ''[[:en:create:functions:setnextpage]]'' ensures that the "next" button leads to page 3. 

<code php>
buttonCode('details', 'complete information', '%details%');
setNextPage('start');
</code>

This PHP code is placed on page 1, followed by the text with the summary, which, in turn, contains the placeholder ''%details%'' at a suitable position. 

Conversely, ''buttonToPage()'' can also be used to allow respondents to skip a section they don't want to answer. However, if the relevance of a section is evident from the previous questions, a [[:en:create:filters|filter question]] usually provides a better solution. 

Furthermore, you can also use the function ''[[:en:create:functions:textlink]]'' which displays extensive information in a pop-up window. 
===== JavaScript =====

The function ''buttonToPage()'' returns a button which appearance can be customized by CSS. But in principle it is also possible to link the behavior with other HTML elements.

In order for the questionnaire to accept the jump order, the ''buttonToPage()'' function must first be called with the desired jump target.

<code php>
buttonToPage('pageID');
</code>

Next, a JavaScript function is required that writes the appropriate data to the questionnaire page and then submits the page by clicking the "Next" button. This function is defined in the following HTML code. Additionally, a normal link is defined there using ''<a>'' and the function is linked to this link using ''addEventListener()'' (at the very end). The second event listener for ''"contextmenu"'' intercepts a right click.

<code html>
<a id="submitLink" href="https://www.soscisurvey.de">www.soscisurvey.de</a>

<script type="text/javascript">
function goButton(evt) {
  var field = document.createElement("input");
  field.setAttribute("type", "hidden");
  field.setAttribute("name", "submitGo");
  field.setAttribute("value", "pageID");  // Hier die passende Seite-Kennung eintragen!
  // Apppend the hidden input to the questionnaire form
  var form = SoSciTools.getForm();
  form.appendChild(field);
  // Submit the page
  SoSciTools.submitPage();
  // Do not follow the original link
  evt.preventDefault();
  return false;
}

// Change the behavior of the link
document.getElementById("submitLink").addEventListener("click", goButton);
document.getElementById("submitLink").addEventListener("contextmenu", goButton);
</script>
</code>

The page ID, that is written into the form field by the JavaScript function, must be the same as in the previous call of ''buttonToPage()'' and both contents (PHP code and HTML code) must be on the same questionnaire page.

Now when you click on the link, the click will be redirected as if you had clicked on the button to the page "pageID".

**Note:** Some browsers may block intercepting the right click - so it may well happen that users go directly to the linked page via right click -> //open on new page//.

===== Button to the table of contents =====

In this section, the use case is explained where the questionnaire has several sections that can be accessed via a table of contents. For this purpose, a page is created as a table of contents, and an additional "Overview" button is placed between the Back and Next buttons.

  *Assign a page identifier to the first page of each section. 
  *Place buttons to the different sections on the first page (table of contents) using ''buttonToPage()''. This could look like the following. 

<code php>
html(
    '<div>'.buttonToPage('abschnitt1', 'Abschnitt 1').'</div>'.
    '<div>'.buttonToPage('abschnitt2', 'Abschnitt 2').'</div>'.
    '<div>'.buttonToPage('abschnitt3', 'Abschnitt 3').'</div>'
);
</code>

  *Assign the page identifier ''content'' to the page with the table of contents.
  *Modify the questionnaire layout by inserting the following HTML code with placeholders. This code allows for the easy placement of a third button between "Back" and "Next". To do this, look for the line ''%questionnaire%'' in the [[:en:create:layout|Questionnaire Layout]] tab //HTML template of the layout// and insert the code below it
 
<code html>
<div style="display: flex; justify-content: space-between; margin-top: 2em;">
    <div>%button.back%</div>
    <div>%button.custom%</div>
    <div>%button.next%</div>
</div>
</code>

  *On the first page of the questionnaire, also use the following request of ''buttonToPage()'' to display the third button.

<code php>
buttonToPage('content', 'Übersicht', '%button.custom%');
</code>