Gewusst-wie: LUA-Skripte in EFS

LUA-Skripte in EFS Survey-Filtern und dem LUA-Fragetyp bieten Benutzern mit Programmierkenntnissen mehr Flexibilität und Komfort. Der LUA-Fragetyp, der sich in "Erweitert" befindet, bietet eine effiziente Skriptschnittstelle zur Umfrageumgebung, die es Benutzern ermöglicht Variablen der Umfrage neu zu kodieren, komplexe Berechnungen durchzuführen, Benutzereingaben zu überprüfen oder zu verarbeiten und erweiterte Quotenberechnungen durchzuführen. Der Fragetyp stellt zwei Codeboxen zur Verfügung, die erste wird vor dem Senden der Seite an den Teilnehmer ausgeführt, die zweite Codebox wird ausgeführt, wenn der Benutzer die Seite mit dem LUA-Fragetyp absendet. Sie können auch eigene Funktionsbibliotheken aus der Medienbibliothek einbinden (globale oder projektspezifische, Textdateien mit der Erweiterung .txt oder .lua), so dass Sie häufig verwendete Funktionen projektübergreifend wiederverwenden können. Sie können die Funktion "Frage ausblenden, wenn ..." verwenden, um nur bei bestimmter Bedingung das Skript auszuführen, und Sie können festlegen, ob das Skript bei jedem Aufruf der Seite oder nur einmal ausgeführt werden soll (z. B. bei Verwendung eines Page-Triggers oder des Zurück-Buttons).

Open

Viele Filter, die bei der Arbeit mit EFS-Standardfilterdefinitionen oder alternativen Filterbedingungen viel Aufwand erfordern, lassen sich mit den LUA-Filtern leichter realisieren. So steht z. B. eine Funktion zur Verfügung, die die Behandlung von System-Missings unter Filterbedingungen vereinfacht. Wirklich komplexe Filterbedingungen können leichter abgebildet werden.

Dieses Handbuch stellt Beispiele für häufige Szenarien bei der Programmierung mit LUA in EFS vor und soll keine allgemeine Einführung in LUA sein, für die es mehrere gute Ressourcen gibt [https://www.lua.org/manual/5.1/, https://www.lua.org/pil/contents.html].

EFS Survey verwendet LUA Version 5.1 in seinen LUA-Filtern und LUA-Fragetypen und bietet Zugriff auf fast alle Standard-LUA-Bibliotheken. Aus Sicherheitsgründen sind die Funktionen dofile, load, loadfile, print, require, rawequal, rawget und rawest und die os-Bibliothek in der LUA-Umgebung nicht verfügbar. Die Funktionen os.date und os.time stehen als date() und time() zur Verfügung. Die Funktion mb_strlen ist als string.len verfügbar.

Der Zugriff auf die Lrexlib ist möglich und ermöglicht erweiterte Regular Expressions innerhalb der LUA-Umgebung zum Suchen, Validieren oder Extrahieren von Benutzereingaben, rex_pcre.find (v_1, "\\bhate") sucht beispielsweise nach Wörtern, die mit "hate" beginnen und gibt false zurück, wenn keine Übereinstimmung gefunden wurde. Die vollständige Dokumentation zu rex_pcre finden Sie im Lrexlib Referenzhandbuch.

Survey-Variablen sind innerhalb der LUA-Umgebung über die globale Tabelle _G zugänglich. Die meisten Variablen sind daher über diese globale Tabelle zugänglich, z. B. _G["v_1"] oder _G["code"]. Umfragevariablen (v_xxx) werden ebenfalls als reguläre Variablen in die LUA-Sandbox eingespeist, daher _G["v_1"] == v_1.

Im nächsten Abschnitt finden Sie eine Liste von EFS-spezifischen LUA-Funktionen, die eine zusätzliche Manipulation oder Abfrage von Umfragevariablen ermöglichen.

LUA Cheat Sheet

Dies ist eine kurze Übersicht der Syntax und häufig verwendeter Befehle in LUA, die vollständige LUA Dokumentation finden Sie unter https://www.lua.org/manual/5.1/ und https://www.lua.org/pil/contents.html. EFS-spezifische Funktionen finden Sie im nächsten Abschnitt.

EFS-spezifische Funktionen in LUA-Filtern und LUA-Fragetyp

setVariableValue(varName, varValue)

Weist den Wert der angegebenen v_, c_ oder p_ Variable zu. Die Variable kann an beliebiger Stelle im Fragebogen ein- oder ausgeblendet sein. Der LUA-Fragetyp selbst stellt Variablen zur Verfügung, die zur Speicherung von Informationen verwendet werden können.

Datentypen

• varName string - Variablenname

• varValue string - Wert

setMasterDataValue(varName, varValue)

Diese Funktion wird nur bei Panel- und Stammdatenumfragen ausgeführt. Sie weist den Wert der angegebenen Stammdatenvariablen des aktuellen Teilnehmers zu oder überschreibt ihn und speichert die Variable in der Datenbank.

Datentypen

• varName string - Variablenname

• varValue string - Wert

setQuestionOutput(text)

Setzt die Ausgabe der LUA-Frage. Diese Funktion sollte nur einmal verwendet werden, da nachfolgende Aufrufe frühere Werte überschreiben, außerdem erzeugt diese Funktion nur eine Ausgabe während der Ausführung des Codes beim Rendern der Frage.

Datentypen

• text string - Text, der in der Lua-Frage ausgegeben werden soll

remove_sys_miss(varValue) 

Konvertiert das System-Missing (Code -77) zu 0, um arithmetische Operationen zu erleichtern. Wenn Sie beispielsweise den LUA-Filter "return v_1+v_2+v_3>10" verwenden, werden System-Missings (Code -77) die Berechnungen negativ beeinflussen, daher kann "return remove_sys_miss(v_1)+remove_sys_miss(v_2)+remove_sys_miss(v_3)>10" verwendet werden, um dieses Problem zu vermeiden.

Datentypen

• varValue mixed - die Variable, die verarbeitet werden soll, z. B. remove_sys_missing(_G["v_1"])

• returns int

get_range_count(values, min_code, max_code)

Gibt zurück, wie oft die angegebenen Werte in dem von min_code und max_code angegebenen Bereich liegen. So ist beispielsweise der Bedingungsrückgabewert get_range_count({v_1,v_2,v_3,v_3,v_4,v_5},1,3)>2 wahr, wenn der Teilnehmer in den ersten drei Kategorien der durch v_1-v_5 dargestellten Matrixfrage mehr als zweimal geantwortet hat.

Datentypen

• values array - Liste der Variablen, z. B. {v_1, v_2, v_3, v_4, v_5}

• min_code mixed

• max_code mixed

• returns int

getQuotaDebitValue(id)

Gibt den Soll-Wert der Quote zurück.

Datentypen

• id int - Quoten-ID

• returns int

getQuotaCurrentValue(id)

Gibt den Ist-Wert der Quote zurück, z. B. setVariableValue("v_1", getQuotaCurrentValue(1)).

Datentypen

• id int - Quoten-ID

• returns int

getQuotaFillingDegree(id)

Gibt den Füllgrad der Quote zurück, z. B. setVariableValue("v_1", getQuotaFillingDegree(1)*100 .. " %").

Datentypen

• id int - Quoten-ID

• returns double

getQuotaIds()

Gibt eine Liste der verfügbaren Quoten-IDs zurück.

Datentypen

• returns array

count(condition) 

Liefert die Anzahl der Teilnehmer, die der angegebenen Bedingung entsprechen, und kann verwendet werden, um den Teilnehmern Statistiken anzuzeigen oder dynamisch in Filtern zu leiten, abhängig von den Antworten der anderen Teilnehmer. WARNUNG! Diese Funktion hat Auswirkungen auf die EFS-Performance und sollte nur bei Umfragen mit geringer Beteiligung verwendet werden. Für Quotierungen verwenden Sie bitte die in EFS integrierte Quotenfunktionalität, da diese für diese Aufgabe effizienter ist.

Datentypen

• condition string - bedingter Ausdruck, z. B. (v_1=1 AND v_2=2)

• returns int or bool

in_list(list_id)

Prüft, ob das aktuelle list_element auch in der angegebenen Liste enthalten ist.

Datentypen

• list_id string - Id of a list, e.g. "l_2"

• returns bool

is_repeated_participation()

Diese Funktion prüft, ob der Teilnehmer bereits an der Umfrage teilgenommen hat, und ist nur bei Panelbefragungen (PA und MD) anwendbar.

Datentypen

• returns int, 0 if false or 1 if true

is_assigned_in_or_below(check_metaname, metanames)

Prüft, ob der Teilnehmer Teil der angegebenen Einheiten oder Untereinheiten in der Orgstruktur des ES-Projekts ist. Gilt nur für die Mitarbeiterbefragung.

Datentypen

• check_metaname string - Metaname

• metanames array - Liste der Metanamen, die dem Teilnehmer zugerwiesen sind

• returns bool

is_assigned_in(check_value, codes)

Prüft, ob der Metanamencode des Teilnehmers den angegebenen Unit-Metanamen (Array von Codes) zugeordnet ist. Gilt nur für die Mitarbeiterbefragung.

Datentypen

• check_value string - Metaname

• codes array - Code-Liste

• returns bool

is_assigned_in_branch(check_metaname, metanames)

Prüft, ob der Teilnehmer in einem Teil des angegebenen Einheitenzweiges zugeordnet ist. Gilt nur für die Mitarbeiterbefragung.

Datentypen

• check_metaname string - Metaname

• metanames array - Liste der Metanamen, die dem Teilnehmer zugewiesen sind

• returns bool

check_character_filter_any(needle, haystack)

Überprüft, ob sich die Needle-Zeichenkette in der Haystack-Liste von Zeichenketten befindet. Zeichenketten in Haystack können folgendermaßen voneinander getrennt werden: |, ",", ; oder -.

Datentypen

• needle string

• haystack string

• returns bool

date([format [, time]])

Ersetzt os.date() und gibt eine Zeichenkette oder eine Tabelle zurück, die das Datum und die Uhrzeit enthält (formatiert in Übereinstimmung mit dem vorhandenen Zeichenkettenformat). Weitere Informationen finden Sie unter os.date documentation.

time([table])

Ersetzt os.time() und gibt beim Aufruf ohne Argumente die aktuelle Zeit zurück. Alternativ werden Datum und Uhrzeit zurückgegeben, die in der vorhandenen Tabelle angegeben sind. Weitere Informationen finden Sie unter os.time documentation.

Beispiele für LUA in EFS

Sperren von bestimmten IPs vom Zugriff auf eine Umfrage

Wenn Sie eine überschaubare Liste von IPs haben, die Sie für den Zugriff auf Ihre Umfrage ausschließen möchten, können Sie einen LUA-Filter verwenden, um diese Teilnehmer auszusortieren. Dieser Beispielcode blockiert die IPs 78.34.112.1, 78.34.112.2 und 78.34.112.3 und die Liste kann durch zusätzliche kommagetrennte IPs erweitert werden. Das letzte Element sollte kein Komma hinter sich haben.

Beispielstruktur

Quelltext

Ein zufällig ausgewähltes Element des Tages allen Teilnehmern zeigen

Selektiert einmal täglich, stunden- oder minutenweise ein zufälliges Element aus einer Liste und speichert es in der Variable v_1 für jeden Teilnehmer in der definierten Zeit. Die Funktion math.randomseed setzt die Zufallszahl für die random-Funktion, wird immer die gleiche Zahl verwendet, so wird auch immer der gleiche Zufallswert zurückgegeben. Um die Größe eines Arrays zu erhalten, setzen Sie # vor den Namen des Arrays, z.B. #randomRestaurants.

Quelltext

Ermitteln von Vorname, Nachname und Firmenname aus einer E-Mail-Adresse.

Dieses Beispiel nimmt die in v_1 gespeicherte E-Mail-Adresse und weist den Variablen v_10, v_11 und v_12 den Firmen-, Vor- und Nachnamen zu. Dies funktioniert bei E-Mail-Aliasen mit firstname.lastname@company.tld oder firstname_lastname@company.tld als Format. Wenn der Vor- oder Nachname nicht erkannt wird, wird der jeweiligen Variable kein Wert zugewiesen.  

Quelltext

Auflösen des participant_country Codes

Wenn Sie in den Projekteigenschaften der Umfrage die Einstellung "Standort der Teilnehmer anhand der IP-Adresse ermitteln" aktiviert haben, speichert EFS den Code des Landes der Teilnehmer in der Variable participant_country. Derzeit gibt es keine Möglichkeit, diese Variable in eine andere Variable mit dem Label des Landes zu rekodieren. Mit dem Beispielcode wird der Code in einem Array nachgeschlagen und die Bezeichnung des Landes in v_1 gespeichert. Dies kann verwendet werden, um ein Textfeld vorab auszufüllen, wenn Sie nach dem Standort eines Benutzers fragen, der Beispielcode kann angepasst werden, um participant_country Codes mit Codes eines Auswahlfeldes für die Vorselektion abzugleichen.

Quelltext (aufklappen)

Aktuelle GMT-Zeit abrufen

Dieser Code gibt die serverseitige Zeit in GMT zurück und kann für datumsbezogene Berechnungen verwendet werden.

Beispielcode

Vergleich der Häufigkeit der abgeschlossenen Teilnahmen

Die folgende alternative Filterbedingung prüft, welche von mehreren Möglichkeiten die Teilnehmer bisher bevorzugt haben:

(count['v_1 = 1'] > count['v_2 = 1'] ) AND (count['v_1 = 1'] > count['v_3 = 1'] ) OR (count['v_2 = 1'] > count['v_1 = 1'] ) AND (count['v_2 = 1'] > count['v_3 = 1'] )

• Wenn zum Zeitpunkt, an dem ein Teilnehmer den Filter passiert, v_1 oder v_2 häufiger ausgewählt wurden, ist die Filterbedingung erfüllt.

• Wenn v_3 häufiger ausgewählt wurde, gilt die Bedingung nicht für den aktuellen Teilnehmer. 

Die Verwendung von LUA anstelle der alternativen Filterfunktion hat mehrere Vorteile:

• Geschwindigkeit: Jedes count belastet den Server. In der obigen alternativen Filterbedingung werden counts für dieselbe Variable wiederholt ausgeführt. In der unteren LUA-Bedingung ist für jede Variable nur eine Zählanforderung erforderlich.

• Kurz und übersichtlich: Je mehr Variablen zu prüfen sind, desto länger und verwirrender wird die alternative Filterbedingung. Im untenstehenden LUA-Filter werden dem Abschnitt "Konfiguration" einfach zusätzliche Variablen hinzugefügt.

• Einfachere Wartung und Konfiguration:
  – Wenn Sie Änderungen vornehmen, müssen Sie lediglich die beiden Arrays im Abschnitt "Konfiguration" ändern.
  – Nicht-Programmierer können die Bedingung wiederverwenden, indem sie diese einfach durch Kopieren und Einfügen und ein paar kleine Änderungen übernehmen.

Quelltext

Vergleich von Antwortmustern

Der Filter prüft, ob die Summe der Antworten in einem ersten Zweig gleich der Summe der Antworten in einem zweiten Zweig ist. Im folgenden Beispiel wird aus Gründen der Kürze nur eine dieser Summen gebildet. Die Umfrage enthält Variablen im Bereich v_135 bis v_173.

Die in der alternativen Filterbedingung verwendete Syntax ( v_x > 0 ? 1 :0) stellt sicher, dass Verstecke und unbeantwortete Elemente angemessen berücksichtigt werden:

• Wenn der Teilnehmer v_x > 0 beantwortet hat. Mit v_x > 0 ? 1 wird der Wert einheitlich auf = 1 gesetzt.

• Hat der Teilnehmer ein Element nicht gesehen oder nicht beantwortet, d.h. v_x kleiner oder gleich 0, wird der entsprechende Faktor auf = 0 gesetzt, da System-Missings, wie z.B. -77, eine korrekte Berechnung der Summe verhindern.

(( v_135 > 0 ? 1 :0) + ( v_136> 0 ? 1 :0) + ( v_137 > 0 ? 1 :0) + ( v_138 > 0 ? 1 :0) +( v_139 > 0 ? 1 :0) +( v_140 > 0 ? 1 :0) + ( v_141 > 0 ? 1 :0) + ( v_142 > 0 ? 1 :0) + ( v_143> 0 ? 1 :0) + ( v_144 > 0 ? 1 :0) + ( v_145 > 0 ? 1 :0) + ( v_146 > 0 ? 1 :0) + ( v_147 > 0 ? 1 :0) + ( v_148 > 0 ? 1 :0) + ( v_149 > 0 ? 1 :0) + ( v_150 > 0 ? 1 :0) + ( v_151 > 0 ? 1 :0) +( v_152 > 0 ? 1 :0) +( v_153 > 0 ? 1 :0) +( v_154 > 0 ? 1 :0) +( v_155 > 0 ? 1 :0) +( v_156 > 0 ? 1 :0) +( v_157 > 0 ? 1 :0) +( v_158 > 0 ? 1 :0) +( v_159 > 0 ? 1 :0) + ( v_160 > 0 ? 1 :0) + ( v_161 > 0 ? 1 :0) + ( v_162 > 0 ? 1 :0) + ( v_163 > 0 ? 1 :0) + ( v_164 > 0 ? 1 :0) +( v_165 > 0 ? 1 :0) +( v_166 > 0 ? 1 :0) +( v_167> 0 ? 1 :0) +( v_168 > 0 ? 1 :0) +( v_169> 0 ? 1 :0) + ( v_170 > 0 ? 1 :0) +( v_171 > 0 ? 1 :0) +( v_172 > 0 ? 1 :0) +( v_173 > 0 ? 1 :0)) [...etc]

Mit LUA kann dies viel einfacher erreicht werden, indem eine for-Schleife erstellt und ein Zähler im Bereich von 135 bis 173 übergeben wird, alternativ kann der for-Schleife ein Array von spezifischen Variablen-IDs zugeführt werden.

Quelltext

Mein Code funktioniert nicht, was soll ich tun?

Überprüfen Sie zunächst, ob im Umfragemenü Triggerfehler gemeldet wurden, EFS zeigt den Umfrageteilnehmern in der Befragung keine LUA-Fehler an. Sie können auch im Menü Test und Validierung -> Projektprüfung, auf Fehler in "Fehler während des Umfragedurchlaufs" klicken, um eine Liste aller Triggerfehler in Ihrer Umfrage zu erhalten. Überprüfen Sie auch den Ausführungszeitpunkt des LUA Codes an, ob dieser beim Laden der Seite oder erst beim Absenden der Seite verarbeitet wird und ob alle benötigten Variablen beim Ausführen des LUA Codes bereits vom Teilnehmer ausgefüllt wurden.

Es empfiehlt sich hartnäckige Fehler in externen LUA-Sandboxen zu debuggen, z.B. online unter repl.it oder in einer lokalen LUA 5.1-Sandbox auf Ihrem Computer. Sie müssen alle EFS-Variablen oder EFS-spezifischen Funktionen in der externen LUA-Sandbox anlegen, siehe Beispiel am Ende dieser Seite.

Bitte beachten Sie, dass das EFS-Supportteam Ihnen nicht bei der Fehlerbehebung Ihres LUA-Codes helfen kann.

Nützliche LUA-Ressourcen

• Deutsches Handbuch zu Lua 5.1, LUA 5.1 Reference Manual

• Programming in LUA 5.0, kostenlos für den persönlichen Gebrauch

• Beschreibung der LUA Bibliotheken

• Lrexlib reference manual

• Repl.it bietet eine komfortable LUA 5.1 Online-Umgebung zum Schreiben und Debuggen von LUA-Code in einer kontrollierten Arbeitsumgebung. Einige EFS-Funktionen können durch Umschreiben emuliert werden, siehe Beispiel unten.

Open

Beispiele zu repl.it