Control Scripte

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

Documentation