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>

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