formgen Control Scripte
Einführung
formgen bietet die Möglichkeit zu definierbaren Zeitpunkten in den Ablauf des Fragebogens per Scripting einzugreifen. Die Möglichkeiten sind sehr umfangreich und werden anhand von Beispielen konkretisiert.
Die Skriptsprache enspricht der Java Syntax und wird, während der Fragebogen läuft, interpretiert.
Lebenszyklus
Zum gezielten Eingreifen in die Verarbeitung werden verschiedenen sog.
callbacks in der Scriptsprache angeboten. Der Lebenszyklus des Fragebogens dient in der zeitlichen Achse als Vorgabe.
customproxy - Die Methode
customproxy wird aufgerufen, um eine Transformation aus dem in der Datenbank gespeicherten "Roh-Fragebogen" (das model.Questionaire Objekt) auszuführen. Das Ergebnis der Transformation ist der dem User angezeigte Fragebogen (das QuestionaireProxy Object)
QuestionaireProxy customproxy(com.pilodata.formgen.model.Questionaire model, QstContext context)
init - Wenn die Struktur des Fragebogens steht, wird
init aufgerufen. Der Fragebogen ist als Variable
qst verfügbar. Ab hier können Ein- oder Ausstiegspunkte für die Seiten gesetzt werden.
void init()
enter - Die Antworten der User sind ab hier geladen. Das Objekt
condition ist verfügbar und Fragen/Antworten können ab hier ein- und ausgeblendet werden.
void enter(TagletContext ctx)
start - Die erste Seite des Fragebogens wird dargestellt
void start()
nextPage - Die Funktion
nextPage wird jedesmal beim Blättern aufgerufen
boolean nextPage(int currentPage, int nextPage)
exit - Die Funktion
exit wird beim Ausstieg des Users aus dem Fragebogen aufgerufen
void exit(TagletContext ctx)
Die Variable qst
Die Variable
qst ist eine Control-Fassade auf den Fragebogen und ermöglicht das steuern des Fragebogens zur Laufzeit.
Es stehen folgende Methoden zur Verfügung:
// Definiert einen callback
public void pagecall(int page, String mode, String command);
// Setzt den Fragebogen auf diese Seite, Wert von -1 beendet den Fragebogen
public void jump(int page);
// Liefert die aktuelle Antwortstruktur
public UserAnswers getUserAnswers();
// Sucht eine Frage anhand des Kurzcodes im gesamten Fragebogen
public Question findQuestion(String code);
// Liefert die Seite, ermöglicht das Verändern der Seite zur Laufzeit
public QuestionairePage getQuestionairePage(int page);
// Liefert einen Evaluator
public QuestionaireEvaluator getEvaluator();
// Setzt eine globale Variable im Fragebogen
public void setVariable(String name, Object value);
// Liest eine globale Variable
public Object getVariable(String name);
// Setzt die Endeseite neu
public void setTargetURL(String targetURL);
// Liefert die aktuelle Sprache
public Locale getLocale();
// Speichert die UserAnswers Data
public void savePoint();
In den Beispiel weiter unten wird die Benutzung der Methoden klar.
Beispiele
Folgende Beispiele sollen die Verwendung der Scripte verdeutlichen.
Fragebogen bei der Instanziierung verändern
Hier wird eine Transformation durchgeführt. Ausgangsbasis ist der in der Datenbank definierte Fragebogen. Als Ergebnis wird der User Fragebogen erzeugt.
Beispiel 1: Verwürfelt die Seiten 2,3,4 und die Seiten 7,8,9,10 auf dem Fragebogen
QuestionaireProxy customproxy(com.pilodata.formgen.model.Questionaire model, QstContext context) {
PageShuffleQuestionaireProxy sp = new PageShuffleQuestionaireProxy(model, context);
sp.shuffle(new int[] {2,3,4});
sp.shuffle(new int[] {7,8,9,10});
return sp;
}
Beispiel 2: Baut einen Fragebogen schrittweise zusammen
QuestionaireProxy customproxy(com.pilodata.formgen.model.Questionaire model, QstContext context) {
BuildQuestionaireProxy bp = new BuildQuestionaireProxy(model, context);
bp.addQuestionsByGroup(1, "all");
return bp;
}
Veränderung des Fragebogens kurz vor der Anzeige
Beispiel 1: Verändert einen Fragebogen zur Laufzeit und sortiert die Fragen der Gruppe "a" auf der Seite 5 um
void enter(TagletContext ctx) {
com.pilodata.formgen.QuestionairePage qp = qst.getQuestionairePage(5);
qp.shuffleGroup("a");
}
Beispiel 2: Blockrotation von Seiten
(ab Build 1492)
void start() {
BlockModifier bm = new BlockModifier(qst);
bm.addBlock(2);
bm.addBlock(4,5);
bm.shuffle();
}
In diesem Beispiel werden die Seite 2 und die Seiten 4-5 als Blöcke definiert. Über
bm.shuffle() werden diese 2 Blöcke Blöcke dann zufällig verwürfelt.
Weitere Informationen zu den Möglichkeiten des BlockModifiers im eigenen Kapitel [BlockModifier].
Kontrolle während der Ausführung
Beispiel 1: Setzen von globalen Variablen beim Einstieg
void start() {
// Get the "ref" http Parameter
String ref = qst.getVariable("reference");
// Check if not empty
if (StringUtils.isNotEmpty(ref)) {
// Set a global Variable
qst.setVariable("price", "abc");
}
}
Beispiel 2: Callback für einen Event setzen
void init() {
// Define a callback on exit of page 2
qst.pagecall(2, ON_EXIT, "page2()");
}
void page2() {
// Check for question "age"
if(condition.isAnswerSet("age","1") ) {
// Quit Questionnaire
qst.jump(-1);
}
if(condition.isAnswerSet("age","2") ) {
// Jump to page 4
qst.jump(4);
}
}
Bei der Initialisierung des Fragebogens wird die Funktion
page2() registriert. Diese wird beim Verlassen von Seite 2 aufgerufen. Weitere Informationen zu den einzelnen Events hier: [Control Skripte Callbacks].
Beispiel 3: Zwischenspeichern
(ab Build 1511)
Normalerweise wird man Fragebögen auf
Speichern nach jeder Seite konfigurieren. Das kann beim Wiedereinstig in rotierten Seitenblöcken aber zu Problemen führen. Dazu kann man mit
savePoint() im Skript kontrollieren, wann gespeichert wird. Dazu setut man im Fragebogen die Einstellung
Speichern am Ende und bestimmt dann im Skript, wann Zwischengespeichert wird.
void init() {
// Define a callback on exit of page 2
qst.pagecall(2, ON_EXIT, "page2()");
}
void page2() {
qst.savePoint();
}
TODO
- Verstecken von Antworten anhand einer Gruppe bnzw. ziehen von Antworten aus einer Liste