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

''string **buttonToPage**(string //Seite//, [mixed //Beschriftung//, mixed //Platzhalter//, mixed //CSS-Klasse//])''

Mit dieser Funktion können Knöpfe erstellt werden, um innerhalb des Fragebogens zu navigieren. Die Funktion gibt den HTML-Code für den Knopf zurück und speichert diesen (optional) in einem Platzhalter, z.B. zur Verwendung im [[:de:create:layout|Layout]].

  * //Seite//\\ Kennung der Fragebogen-Seite zu der gesprungen werden soll.
    * <[[:de:glossary#seitenkennung|Seiten-Kennung]]> -- Sprung zu einer bestimmten Seite im Fragebogen
    * '''end''' -- Sprung zur letzten Seite (Ende der Befragung)
  * //Beschrifung//\\ Die Beschriftung des Knopfes (Text oder HTML-Code). Wird keine Beschriftung angegeben, so verwendet der Knopf eine für die Fragebogen-Seite eingetragene Notiz oder die Seiten-Kennung.
    * <string> -- Beschriftung unabhängig von der Sprachversion
    * <array> -- Beschriftung je nach Sprachversion. Die Kennung der Sprachversion (z.B. ''"ger"'' oder ''"eng"'') wird als Schlüssel des Arrays verwendet, die eigentliche Beschriftung als zugehöriger Wert.
  * //Platzhalter//\\ Wird als dritter Parameter ein Platzhalter oder ''true'' angegeben, so bleibt der Knopf im gesamten Fragebogen gültig, sonst nur auf der aktuellen Fragebogen-Seite.
    * <[[:de:create:placeholders#regeln_fuer_benutzerdefinierte_platzhalter|Platzhalter]]> -- Der HTML-Code für den Knopf wird im angegeben Platzhalter abgelegt und kann damit z.B. auch im Layout verwendet werden.
    * ''true'' -- Der Knopf ist im gesamten Fragebogen gültig, der HTML-Code muss aber manuell eingebunden werden.
    * ''null'' oder ''false'' -- Der Knopf ist nur auf der aktuellen Seite des Fragebogens gültig.
  * //CSS-Klasse//\\ Dem ''<button>''-Tag, welches für den Knopf verwendet wird, können neben der CSS-Klasse ''buttonToPage'' noch weitere CSS-Klassen als String oder Array beigefügt werden. So lässt sich z.B. eine hierarchische Navigation realisieren.

**Hinweis:** Beim Verlassen einer Seite mit einem Knopf, der mittels ''buttonToPage()'' eingefügt wurde, werden die Antworten auf Pflichtfragen nicht auf Vollständigkeit überprüft.



===== Mehrere Seiten zurück springen =====

Der Teilnehmer soll die Möglichkeit haben, zu einer früheren Seite zu springen.

Geben Sie der Seite, zu welcher der Teilnehmer springen soll, z.B. die Kennung "early" ([[:de:glossary#seitenkennung|Seiten-Kennung]]).

Fügen Sie an der Stelle, wo der Knopf erscheinen soll, folgenden PHP-Code ein ([[:de:create:php]])

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

Das ''<div>''-Tag sorgt dafür, dass der Knopf in einer eigenen Zeile und mit ein wenig Abstand nach oben und unten angezeigt wird.


===== Einfache Navigation =====

Der Teilnehmer soll während der gesamten Befragung die Möglichkeit haben, zu zwei bestimmten Seiten im Fragebogen zu springen.

Geben Sie den beiden Seiten im Fragebogen dafür zunächst Seiten-Kennungen, z.B. "jump1" und "jump2".

Fügen Sie auf der ersten Seite des Fragebogens folgenden PHP-Code ein:

<code php>
buttonToPage('jump1', 'Zur Auswahl', '%btnJ1%');
buttonToPage('jump2', 'Zur Übersicht', '%btnJ2%');
</code>

Fügen Sie in der HTML-Vorlage des Layouts ([[:de:create:layout]]) an geeigneter Stelle (z.B. links in der Navigation, sofern im Layout vorhanden, oder über den Platzhaltern für den Weiter-Knopf) folgenden HTML-Code ein.

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

**Hinweis:** Die Knöpfe werden nur angezeigt, wenn der Fragebogen ab der ersten Seite gestartet wird. Falls Sie den Fragebogen testweise auf einer späteren Seite starten, werden nur die Platzhalter angezeigt.



===== Bearbeiten früherer Abschnitte =====

Wieder sollen im Layout mehrere Knöpfe angeboten werden, um innerhalb des Fragebogens zu navigieren. Allerdings soll ein Sprung nur zu den Kapiteln erlaubt sein, welche der Teilnehmer bereits regulär erreicht hat.

Geben Sie den Seiten, auf welchen die Kapitel beginnen, eindeutige Seiten-Kennungen, z.B. "chapter1" bis "chapter4".

Initialisieren Sie mit folgendem PHP-Code Platzhalter für alle Knöpfe (z.B. "%btnC1%" bis "%btnC5%"). Der IF-Filter mit ''[[:de:create:functions:getroute]]'' stellt sicher, dass die Knöpfe für einmal erreichte Kapitel auch dann erhalten bleiben, wenn der Teilnehmer die erste Seite erneut aufruft.

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

Auf allen 5 Kapitel-Seiten, ab wo der jeweilige Knopf erscheinen soll, fügen Sie folgenden PHP-Code ein. Die Parameter müssen natürlich an die Seite angepasst werden.

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

In der HTML-Vorlage des Layouts fügen Sie wieder Platzhalter für die Knöpfe ein:

<code html>
<!-- Knöpfe untereinander -->
<div style="margin: 2em 0">
  <div>%btnC1%</div>
  <div>%btnC2%</div>
  <div>%btnC3%</div>
  <div>%btnC4%</div>
  <div>%btnC5%</div>
</div>
<!-- Knöpfe nebeneinander -->
<div style="margin: 2em 0">
  %btnC1%
  %btnC2%
  %btnC3%
  %btnC4%
  %btnC5%
</div>
</code>


===== Nicht-lineares Ausfüllen =====

Der Fragebogen soll nicht (unbedingt) linear bearbeitet werden? Mit ''buttonToPage()'' lässt sich auch eine umfangreiche Navigation realisieren.

Als Vorbereitung geben Sie allen Seiten, auf denen ein Abschnitt beginnt, unter **Fragebogen zusammenstellen** eine [[de:glossary#seitenkennung|Seiten-Kennung]] und tragen Sie als Kommentar für die Seite einen Titel für den Abschnitt ein, wie er in der Navigation erscheinen soll.

Es gibt zwei Möglichkeiten, die Navigation auf allen Seiten anzuzeigen:

  - Verwenden Sie Platzhalter und verwenden Sie diese direkt im **Fragebogen-Layout** -> //HTML-Vorlage// vor dem Platzhalter ''%questionnaire%'' -- dann muss der PHP-Code mit ''buttonToPage()'' nur einmal auf der ersten Seite des Fragebogens platziert werden, aber die aktuelle Seite kann bei dieser Lösung nicht farblich hervorgehoben werden.
  - Platzieren Sie den PHP-Code für die Navigation auf jeder Seite des Fragebogens, z.B. oben auf jeder Seite. Nachfolgend ein Beispiel, wie der PHP-Code dafür aussehen könnte:

<code php>
html(
  // Ein <div> sorgt für die optische Abgrenzung zwischen Navigation und Seiteninhalt
  '<div style="border: 2px solid #CCCCCC; border-left: 0 none; border-right: 0 none; padding: 20px 0 12px 0; margin-bottom: 3em;">'.
  // Ein weiteres <div> erlaubt die flexible Anordnung der Navigations-Schaltflächen
  '<div class="s2flex navButtons" style="flex-wrap: wrap; margin-right: -8px">'.NL.
  buttonToPage('start').
  buttonToPage('kontakt').
  buttonToPage('studium').
  buttonToPage('leistungen').
  buttonToPage('dokumente').
  buttonToPage('notizen').
  '<div style="width: 2em;"></div>'.
  buttonToPage('abschicken').
  '</div>'.
  '</div>'
);
</code>

Möchte man die Knöpfe noch ein wenig ansprechender gestalten, kann man im **Fragebogen-Layout** in der //HTML-Vorlage// im ''<style>''-Bereich noch ein wenig CSS-Code ergänzen:

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


===== Mehrsprachige Beschriftung =====

In einem mehrsprachigen Fragebogen ([[:de:create:multilang]]) müssen die Beschriftungen der Knöpfe je nach Sprachversion angepasst werden. Dafür kann dem zweiten Parameter ein Array übergeben werden.

Ermitteln Sie unter **Sprachversionen** zunächst, welchen (dreistelligen) Code die verwendeten Sprachen haben. Das folgende Beispiel verwendet unterschiedliche Beschriftungen für die Sprache "Deutsch (Sie)", Code "ger" und "Englisch", 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>

Dieselbe Konstruktion ist auch mit Platzhaltern möglich (die drei Schreibweisen demonstrieren lediglich, wie Sie den PHP-Code je nach Geschmack auf mehrere Zeilen verteilen können).

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


===== Optionale Seiten =====

Eine weitere Anwendung von ''buttonToPage()'' besteht darin, dass man optionale Seiten oder Abschnitte im Fragebogen realisieren kann. So könnte eine [[:de:create:consent|informierte Einwilligung]] zunächst nur die Kurzfassung der Informationen präsentieren und per Klick auf den Knopf "Vollständige Informationen" gelangt man auf eine Seite, welche die detaillierte Darstellung beinhaltet.

In der praktichen Umsetzung würde man die Seite mit der vollständigen Information überspringen, wenn die befragte Person nur auf "Weiter" klickt. Man hätte also folgende Seiten:

  * Seite 1 mit der Kurzfassung
  * Seite 2 ("details") mit der detaillierten Information
  * Seite 3 ("start") auf welcher der eigentliche Fragebogen beginnt

Der PHP-Code würde nun den Platzhalter ''%details%'' mit einem Knopf zur Seite 2 belegen, während ''[[:de:create:functions:setnextpage]]'' dafür sorgt, dass der "Weiter"-Knopf zur Seite 3 führt.

<code php>
buttonCode('details', 'Vollständige Informationen', '%details%');
setNextPage('start');
</code>

Dieser PHP-Code wird auf Seite 1 platziert, darunter der Text mit der Kurzfasssung, welche an geeigneter Stellen den Platzhalter ''%details%'' verwendet.

Umgekehrt kann ''buttonToPage()'' natürlich auch verwendet werden, damit Befragte einen Abschnitt überspringen können, den sie nicht beantworten möchten. Wenn die Relevanz eines Abschnitts aus den bisherigen Fragen hervor geht, ist eine [[:de:create:filters|Filterfrage]] in aller Regel aber die bessere Lösung.

Weiterhin sei auf die Funktion ''[[:de:create:functions:textlink]]'' verwiesen, welche einen umfangreichen Informationstext in einem Pop-Up-Fenster anzeigt.

===== JavaScript =====

Die Funktion ''buttonToPage()'' liefert einen Knopf, dessen aussehen mittels CSS auch angepasst werden kann. Aber im Prinzip ist auch möglich, das Verhalten mit anderen HTML-Elementen zu verknüpfen.

Damit der Fragebogen den Sprungbefehl entgegennimmt, muss der ''buttonToPage()'' Befehl zunächst einmal mit dem gewünschten Sprungziel aufgerufen werden.

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

Weiterhin ist eine JavaScript-Funktion erforderlich, welche die passenden Daten in die Fragebogen-Seite schreibt und anschließend die Seite mittels "Weiter" abschickt. Diese ist im folgenden HTML-Code definiert. Zusätzlich wird dort ein normaler Links mittels ''<a>'' definiert und die Funktion mittels ''addEventListener()'' (ganz am Ende) an diesen Link gekoppelt. Der zweite Event-Listener für ''"contextmenu"'' fängt einen Rechtsklick ab.

<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");  // Enter the appropriate page ID here!
  // 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>

Die Seiten-Kennung, welche in der JavaScript-Funktion in das Formularfeld geschrieben wird, muss dieselbe sein wie im vorigen Aufruf von ''buttonToPage()'' und beide Inhalte (PHP-Code und HTML-Code) müssen auf derselben Fragebogen-Seite stehen.

Wenn man nun auf den Link klickt, wird der Klick so ungeleitet, als hätte man auf den Knopf zur Seite "pageID" geklickt.

**Hinweis:** Einige Browser sperren womöglich das Abfangen des Rechtsklicks - es kann also durchaus passieren, dass Nutzer über Rechtsklick -> //auf neuer Seite öffnen// direkt auf die verlinkte Seite gelangen.


===== Knopf zum Inhaltsverzeichnis =====

In diesem Abschnitt wird der Anwendungsfall erklärt, dass der Fragebogen mehrere Abschnitte hat, welche über ein Inhaltsverzeichnis zu erreichen sind. Dafür wird eine Seite als Inhaltsverzeichnis erstellt und zwischen Zurück- und Weiter-Knopf wird ein zusätzlicher Knopf "Übersicht" platziert.

  * Geben Sie der jeweils ersten Seite in jedem Abschnitt eine Seitenkennung.
  * Platzieren Sie auf der ersten Seite (Inhaltsverzeichnis) mittels ''buttonToPage()'' Knöpfe zu den unterschiedlichen Abschnitten. Das kann zum Beispiel wie folgt aussehen.

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

  * Geben Sie der Seite mit dem Inhaltsverzeichnis die Seitenkennung ''content''.
  * Modifizieren Sie das Fragebogen-Layout, indem Sie folgenden HTML-Code mit Platzhaltern einfügen. Dieser Code ermöglicht die einfache Platzierung eines dritten Knopfes zwischen "Zurück" und "Weiter". Suchen Sie dafür im [[:de:create:layout|Fragebogen-Layout]] im Karteireiter //HTML-Vorlage des Layouts// die Zeile ''%questionnaire%'' und fügen Sie darunter ein

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

  * Verwenden Sie auf der ersten Seite des Fragebogens zusätzlich noch folgenden Aufruf von ''buttonToPage()'', um den dritten Knopf anzuzeigen.

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