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

• page
  questionaire ID to which one leaps by clicking the button.
  • <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.
  • <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.

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” (Page IDs).

Add the followin PHP-Code at the place where the button shall appear (Introduction to PHP)

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

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.

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:

buttonToPage('jump1', 'To the selection', '%btnJ1%');
buttonToPage('jump2', 'To the overview', '%btnJ2%');

Add in the HTML-template of the layout (Questionnaire 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.

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

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.

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 getRoute() makes sure, that buttons for chapters that have been reached are kept if the participant reloads the first page.

if (getRoute() == 'start') {
  replace('%btnC1%', '');
  replace('%btnC2%', '');
  replace('%btnC3%', '');
  replace('%btnC4%', '');
  replace('%btnC5%', '');
}

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.

buttonToPage('chapter1', 'chapter 1', '%btnC1%');

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

<!-- 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>

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 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:

1. 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.
2. 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:

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>'
);

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:

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;
}

In a multilingual questionnaire (Multilingual Surveys) 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>
html(
  '<div style="text-align: center; margin: 2em 0">'.
  buttonToPage('early', array(
    'ger' => 'Zurück zur Auswahl',
    'eng' => 'Back to Selection'
  )).
  '</div>'
);

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

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%'
);

Another application of buttonToPage() is that you can implement optional pages or sections in the questionnaire. For example, 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 setNextPage() ensures that the “next” button leads to page 3.

buttonCode('details', 'complete information', '%details%');
setNextPage('start');

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 filter question usually provides a better solution.

Furthermore, you can also use the function textlink() which displays extensive information in a pop-up window.

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.

buttonToPage('pageID');

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.

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

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.

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.

html(
    '<div>'.buttonToPage('section1', 'Section 1').'</div>'.
    '<div>'.buttonToPage('section2', 'Section 2').'</div>'.
    '<div>'.buttonToPage('section3', 'Section 3').'</div>'
);

• 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 Questionnaire Layout tab HTML template of the layout and insert the code below it

<div style="display: flex; justify-content: space-between; margin-top: 2em;">
    <div>%button.back%</div>
    <div>%button.custom%</div>
    <div>%button.next%</div>
</div>

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

buttonToPage('content', 'Table of Contents', '%button.custom%');