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.

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