====== multiLevelPrepare() ======

''int **multiLevelPrepare**(string //Fragebogen//, [array //Daten//])''

Die Funktion ''multiLevelPrepare()'' erstellt einen untergeordneten Fall im Datensatz ([[:de:create:multilevel]]). Variablen im neuen Fall können vorbelegt werden. Diese Funktion ist vor allem in Verbindung mit einer [[:de:create:questions:multilevel]] sinnvoll nutzbar.

  * //Fragebogen// -- Die Kennung des Fragebogens, welches zum Bearbeiten des untergeordneten Falls verwendet werden soll.
  * //Daten// -- Ein assoziatives [[:de:create:array|Array]] aus Variablennamen und Werten, welche Werte in dem neuen Fall vorbelegt werden sollen.

Es wird jeweils nur ein Fall mit den vorgegeben Daten erstellt, auch wenn die Funktion mehrfach aufgerufen wird.

  * Es ist daher unproblematisch, wenn die Seite mit dem Aufruf mehrfach ausgeführt wird.
  * Wenn mehrere Fälle erstellt werden sollen, müssen die übergebenen //Daten// variieren.


===== Rückgabewert =====

Die Funktion gibt die Fallnummer (CASE) des neu erstellen Falls im Datensatz zurück.


===== Beispiel =====

In aller Regel möchten Sie bei der Verwendung von ''multiLevelPrepare()'' gleich eine Information (hier z.B. einen Namen) für jeden untergeordneten Fall hinterlegen. Dafür verwenden Sie eine [[:de:create:questions:internal|interne Variable]], die Sie im Fragenkatalog separat anlegen.

Der folgende PHP-Code erstellt für jeden Namen in der Liste ''$namen'' einen untergeordneten Fall im Datensatz für den Fragebogen ''personenangaben'' und speichert den Namen jeweils in der internen Variable ''TX01_01''.

<code php>
foreach ($namen as $name) {
    multiLevelPrepare('personenangaben', ['TX01_01' => $name]);
}
</code>

Unterhalb des PHP-Codes könnte hier eine Frage vom Typ [[:de:create:questions:multilevel]] platziert werden, welche den Aufruf der jeweiligen Fälle zum Eingeben der Personenangaben erlaubt. In der Multi-Level Übersicht würden Sie als //Variable für den Titel// wieder ''TX01_01'' eintragen, damit die Liste alle Namen anzeigt.

Im untergeordneten Fragebogen kann der Name dann über ''value('TX01_01')'' ausgelesen und z.B. mittels ''html()'' angezeigt werden.

<code php>
// Direkt anzeigen
html('<h1>'.value('TX01_01').'</h1>');

// Anzeige mittels Platzhalter, zum Beispiel für weitere Fragen
replace('%name%', 'TX01_01', 'response');
html('<h1>%name%</h1>');
</code>