Funktionen

Zeichenkettenfunktionen link

rtSurvey unterstützt verschiedene Funktionen, darunter:

1. string(field): Wandelt ein Feld in eine Zeichenkette um.

   • Beispiel: string(34.8) wird in '34.8' umgewandelt.

2. string-length(field): Gibt die Länge eines Zeichenkettenfeldes zurück.

   • Beispiel: string-length(.) > 3 and string-length(.) < 10 kann verwendet werden, um sicherzustellen, dass das aktuelle Feld zwischen 3 und 10 Zeichen lang ist.

3. substr(fieldorstring, startindex, endindex): Gibt einen Teilstring zurück, der bei startindex beginnt und kurz vor endindex endet. Indizes beginnen bei 0 für das erste Zeichen in der Zeichenkette.

   • Beispiel: substr(${phone}, 0, 3) gibt die ersten drei Ziffern einer Telefonnummer zurück.

4. concat(a, b, c, ...): Verkettet Felder (und/oder Zeichenketten) miteinander.

   • Beispiel: concat(${firstname}, ' ', ${lastname}) gibt einen vollständigen Namen zurück, indem die Werte in den Feldern firstname und lastname kombiniert werden.

5. linebreak(): Gibt ein Zeilenumbruchzeichen zurück.

   • Beispiel: concat(${field1}, linebreak(), ${field2}, linebreak(), ${field3}) gibt eine Liste von drei Feldwerten mit Zeilenumbrüchen dazwischen zurück.

6. lower(): Wandelt eine Zeichenkette in Kleinbuchstaben um.

   • Beispiel: lower('Street Name') gibt “street name” zurück.

7. upper(): Wandelt eine Zeichenkette in Großbuchstaben um.

   • Beispiel: upper('Street Name') gibt “STREET NAME” zurück.

Funktionen für select_one und select_multiple link

1. count-selected(field): Gibt die Anzahl der ausgewählten Elemente in einem select_multiple-Feld zurück.

   • Beispiel: count-selected(.) = 3 kann als Einschränkungsausdruck verwendet werden, um sicherzustellen, dass genau drei Auswahlmöglichkeiten ausgewählt wurden.

2. selected(field, value): Gibt wahr oder falsch zurück, je nachdem, ob der angegebene Wert im select_one- oder select_multiple-Feld ausgewählt wurde.

   • Beispiel: selected(${color}, 'Blue') kann als Relevanzausdruck verwendet werden, um eine Gruppe oder ein Feld nur anzuzeigen, wenn der Befragte “Blau” als Lieblingsfarbe ausgewählt hat.
   • Hinweis: Der zweite Parameter sollte immer den Auswahlwert angeben, nicht die Auswahlbeschriftung.

3. selected-at(field, number): Gibt das ausgewählte Element an der angegebenen Position in einem select_multiple-Feld zurück. Wenn die übergebene Zahl 0 ist, wird das erste ausgewählte Element zurückgegeben; bei 1 das zweite usw.

   • Beispiel: selected-at(${fruits}, 0) = 'Apple' kann als Relevanzausdruck verwendet werden, um eine Gruppe nur anzuzeigen, wenn die erste ausgewählte Option “Apple” ist.
   • Hinweis: Der zurückgegebene Wert ist der Auswahlwert, nicht die Auswahlbeschriftung.

4. choice-label(field, value): Gibt die Beschriftung für eine select_one- oder select_multiple-Feldauswahl zurück, wie im choices-Arbeitsblatt definiert.

   • Beispiel 1: choice-label(${country}, ${country}) gibt die Auswahlbeschriftung für die aktuell ausgewählte Option im Feld country zurück.
   • Beispiel 2: choice-label(${languages}, selected-at(${languages}, 0)) gibt die Beschriftung für die erste ausgewählte Option im Feld languages zurück.
   • Hinweis: Diese Funktion ruft die Auswahlbeschriftung ab, nicht den Wert.

Funktionen für Wiederholungsfelder link

In rtSurvey können Sie, wenn Sie dieselbe(n) Frage(n) mehrfach stellen möchten, ein Feld in eine Wiederholungsgruppe einfügen. Dies führt zu mehreren Instanzen desselben Feldes. Die folgenden Funktionen helfen bei der Arbeit mit diesen wiederholten Feldern und den von ihnen erzeugten Daten.

1. join(string, repeatedfield): Generiert für ein Feld innerhalb einer Wiederholungsgruppe eine durch eine Zeichenkette getrennte Liste von Werten. Der erste Parameter gibt das Trennzeichen an.

   • Beispiel: join(', ', ${member_name}) generiert eine einzelne kommagetrennte Liste aus allen eingegebenen Namen.

2. join-if(string, repeatedfield, expression): Funktioniert genau wie join(), prüft jedoch jede Instanz in der Wiederholungsgruppe mit dem angegebenen Ausdruck. Wenn der Ausdruck falsch ergibt, wird das Element aus der Ausgabe ausgelassen.

   • Beispiel: join-if(', ', ${member_name}, ${age} >= 18) generiert eine kommagetrennte Liste von Namen nur erwachsener Mitglieder.

3. count(repeatgroup): Gibt die aktuelle Anzahl der Wiederholungen einer Wiederholungsgruppe zurück.

   • Beispiel: count(${groupname}) gibt die Anzahl der Instanzen der Gruppe zurück.

4. count-if(repeatgroup, expression): Funktioniert wie count(), prüft jedoch jede Instanz mit dem angegebenen Ausdruck. Wenn der Ausdruck falsch ergibt, wird das Element nicht gezählt.

   • Beispiel: count-if(${members}, ${age} >= 18) gibt die Anzahl der erwachsenen Mitglieder zurück.

5. sum(repeatedfield): Berechnet für ein Feld innerhalb einer Wiederholungsgruppe die Summe aller Werte.

   • Beispiel: sum(${loan_amount}) gibt den Gesamtwert aller Darlehen zurück.

6. sum-if(repeatedfield, expression): Funktioniert wie sum(), prüft jedoch jede Instanz mit dem angegebenen Ausdruck.

   • Beispiel: sum-if(${loan_amount}, ${loan_amount} > 500) gibt den Gesamtwert aller Darlehen über 500 zurück.

7. min(repeatedfield): Berechnet für ein Feld innerhalb einer Wiederholungsgruppe den Minimalwert aller Werte.

   • Beispiel: min(${member_age}) gibt das Alter des jüngsten Mitglieds zurück.

8. min-if(repeatedfield, expression): Funktioniert wie min(), prüft jedoch jede Instanz mit dem angegebenen Ausdruck.

   • Beispiel: min-if(${member_age}, ${member_age} >= 18) gibt das Alter des jüngsten Erwachsenen zurück.

9. max(repeatedfield): Berechnet für ein Feld innerhalb einer Wiederholungsgruppe den Maximalwert aller Werte.

   • Beispiel: max(${member_age}) gibt das Alter des ältesten Mitglieds zurück.

10. max-if(repeatedfield, expression): Funktioniert wie max(), prüft jedoch jede Instanz mit dem angegebenen Ausdruck.

    • Beispiel: max-if(${member_age}, ${member_age} >= 18) gibt das Alter des ältesten Erwachsenen zurück.

11. index(): Wird innerhalb einer Wiederholungsgruppe aufgerufen und gibt die Indexnummer der aktuellen Gruppe oder Instanz zurück.

    • Beispiel: index() gibt bei Verwendung innerhalb einer Wiederholungsgruppe 1 für die erste Instanz zurück, 2 für die zweite usw.

12. indexed-repeat(repeatedfield, repeatgroup, index): Referenziert ein Feld oder eine Gruppe, die sich innerhalb einer Wiederholungsgruppe befindet, von außerhalb dieser Wiederholungsgruppe. Der erste Parameter gibt das wiederholte Feld oder die Gruppe an, der zweite die Wiederholungsgruppe, in der sich das Feld befindet, und der dritte die Instanznummer.

    • Beispiel 1: indexed-repeat(${name}, ${names}, 1) gibt den ersten Namen zurück, wenn das Namensfeld in einer vorherigen Wiederholungsgruppe namens “names” liegt.
    • Beispiel 2: indexed-repeat(${name}, ${names}, index()) ruft den Namen ab, der der Instanznummer der aktuellen Wiederholungsgruppe entspricht.

13. rank-index(index, repeatedfield): Diese Funktion berechnet den ordinalen Rang der angegebenen Instanz eines wiederholten Feldes zur Verwendung außerhalb der Wiederholungsgruppe. Der Rang 1 wird der Instanz mit dem höchsten Wert zugewiesen, der Rang 2 der Instanz mit dem nächsthöheren Wert usw.

    • Beispiel: rank-index(1, ${random_draw}) berechnet den Rang der ersten Instanz basierend auf dem Wert ihres random_draw-Feldes im Vergleich zu anderen Instanzwerten.

14. rank-index-if(index, repeatedfield, expression): Diese Funktion funktioniert ähnlich wie rank-index(), prüft jedoch jede Instanz mit dem angegebenen Ausdruck. Wenn der Ausdruck falsch ergibt, wird das Element aus der Berechnung ausgelassen.

    • Beispiel: rank-index-if(1, ${age}, ${age} >= 18) berechnet den Altersrang innerhalb der Gruppe der Erwachsenen.

Zahlenfunktionen link

rtSurvey unterstützt Zahlenfunktionen, darunter:

• number(field): Wandelt den Wert des Feldes in eine Zahl um.

  • Beispiel: number('34.8') = 34.8

• int(field): Wandelt den Wert des Feldes in eine Ganzzahl um.

  • Beispiel: int('39.2') = 39

• min(field1, ..., fieldx): Gibt den Minimalwert unter den übergebenen Feldern zurück.

  • Beispiel: min(${father_age}, ${mother_age}) gibt das Alter von Vater oder Mutter zurück, je nachdem, welches kleiner ist.

• max(field1, ..., fieldx): Gibt den Maximalwert unter den übergebenen Feldern zurück.

  • Beispiel: max(${father_age}, ${mother_age}) gibt das Alter von Vater oder Mutter zurück, je nachdem, welches größer ist.

• format-number(field): Formatiert den Wert eines Ganzzahl- oder Dezimalfeldes gemäß den Gebietsschema-Einstellungen des Benutzers.

  • Beispiel: format-number(${income}) könnte “120000” als “120.000” formatieren.

• round(field, digits): Rundet den numerischen Feldwert auf die angegebene Anzahl von Dezimalstellen.

  • Beispiel: round(${interest_rate}, 2)

• abs(number): Gibt den absoluten Wert einer Zahl zurück.

• pow(base, exponent): Gibt den Wert des ersten Parameters hoch des zweiten Parameters zurück.

  • Jeder Parameter kann ein Feld, eine Zahl oder ein Ausdruck sein.

• log10(fieldorvalue): Gibt den dekadischen Logarithmus des übergebenen Feldes oder Werts zurück.

• sin(fieldorvalue): Gibt den Sinus des übergebenen Feldes oder Werts zurück, ausgedrückt in Radiant.

• cos(fieldorvalue): Gibt den Kosinus des übergebenen Feldes oder Werts zurück, ausgedrückt in Radiant.

• tan(fieldorvalue): Gibt den Tangens des übergebenen Feldes oder Werts zurück, ausgedrückt in Radiant.

• asin(fieldorvalue): Gibt den Arkussinus des übergebenen Feldes oder Werts zurück, ausgedrückt in Radiant.

• acos(fieldorvalue): Gibt den Arkuskosinus des übergebenen Feldes oder Werts zurück, ausgedrückt in Radiant.

• atan(fieldorvalue): Gibt den Arkustangens des übergebenen Feldes oder Werts zurück, ausgedrückt in Radiant.

• atan2(x, y): Gibt den Winkel in Radiant zurück, den der Punkt mit den Koordinaten (x, y) und die positive x-Achse am Ursprung einschließen. Das Ergebnis liegt im Bereich -pi() bis pi().

• sqrt(fieldorvalue): Gibt die nicht-negative Quadratwurzel des übergebenen Feldes oder Werts zurück.

• exp(x): Gibt den Wert von e^x zurück.

• pi(): Gibt den Wert von Pi zurück.

Datums- und Uhrzeitfunktionen link

1. today(): Gibt das heutige Datum als Zeichenkette im Format YYYY-MM-DD zurück. Wird einmal beim Öffnen des Formulars ausgewertet.

   • Beispiel: today() → '2024-03-15'
   • Häufige Verwendung: Spalte default, um das heutige Datum vorzubefüllen, oder in relevant/constraint, um mit einem Datumsfeld zu vergleichen.

2. now(): Gibt das aktuelle Datum und die aktuelle Uhrzeit als ISO 8601-Zeichenkette zurück. Wird jedes Mal ausgewertet, wenn der Ausdruck berechnet wird.

   • Beispiel: now() → '2024-03-15T14:32:00.000+03:00'
   • Häufige Verwendung: Aufzeichnung des genauen Zeitstempels eines bestimmten Ereignisses während der Umfrage.

3. date(value): Wandelt einen Wert (Zeichenkette oder Zahl) in eine Datumszeichenkette um.

   • Beispiel: date('2024-03-15') → '2024-03-15'

4. date-time(value): Wandelt einen Wert in eine Datetime-Zeichenkette um.

   • Beispiel: date-time(${event_timestamp})

5. decimal-date-time(value): Wandelt eine Datums- oder Datetime-Zeichenkette in eine Dezimalzahl um, die Millisekunden seit der Unix-Epoche geteilt durch 86400000 (d. h. gebrochene Tage seit 1970-01-01) darstellt. Verwenden Sie dies für Arithmetik mit Daten.

   • Beispiel: Dauer in Tagen zwischen zwei Daten: decimal-date-time(${end_date}) - decimal-date-time(${start_date})
   • Beispiel: Dauer in Minuten zwischen zwei Datumszeitangaben: (decimal-date-time(${end_time}) - decimal-date-time(${start_time})) * 1440

6. format-date(date, format): Formatiert einen Datumswert mit einer Formatzeichenkette.

   • Format-Token: %Y (4-stelliges Jahr), %y (2-stelliges Jahr), %m (Monat 01–12), %d (Tag 01–31), %a (abgekürzter Wochentag), %b (abgekürzter Monatsname)
   • Beispiel: format-date(today(), '%d/%m/%Y') → '15/03/2024'
   • Beispiel: format-date(${dob}, '%B %d, %Y') → 'March 15, 1990'

7. format-date-time(datetime, format): Formatiert einen Datetime-Wert mit einer Formatzeichenkette. Akzeptiert alle format-date-Token plus:

   • %H (Stunde 00–23), %h (Stunde 01–12), %M (Minuten 00–59), %S (Sekunden 00–59), %3 (Millisekunden), %P (AM/PM)
   • Beispiel: format-date-time(now(), '%d/%m/%Y %H:%M') → '15/03/2024 14:32'
   • Beispiel: format-date-time(${event_time}, '%I:%M %p') → '02:32 PM'

Boolesche Funktionen link

1. boolean(value): Wandelt einen beliebigen Wert in einen booleschen Wert um. Gibt true für nicht leere Zeichenketten, Zahlen ungleich null und true zurück; gibt false für leere Zeichenketten, 0 und false zurück.

   • Beispiel: boolean(${name}) gibt true zurück, wenn name nicht leer ist.

2. boolean-from-string(string): Gibt true zurück, wenn die Zeichenkette '1' oder 'true' ist (Groß-/Kleinschreibung unerheblich); andernfalls false.

   • Beispiel: boolean-from-string(${enabled_flag}) — nützlich, wenn ein Feld 'true'/'false' als Text speichert.

3. true(): Gibt den booleschen Wert true zurück.

   • Beispiel: In der Spalte required ist true() äquivalent zu yes.

4. false(): Gibt den booleschen Wert false zurück.

   • Beispiel: if(${skip_section} = 'yes', false(), true()) — dynamisch “required” setzen.

5. not(expression): Gibt die logische Negation des Ausdrucks zurück. Gibt true zurück, wenn der Ausdruck falsch ist, und umgekehrt.

   • Beispiel: not(${consent} = 'yes') — eine Warnung anzeigen, wenn keine Zustimmung gegeben wurde.
   • Beispiel: not(selected(${issues}, 'none')) — Details nur erfordern, wenn “keine” nicht ausgewählt wurde.

Weitere Zeichenkettenfunktionen link

1. starts-with(string, prefix): Gibt true zurück, wenn string mit prefix beginnt.

   • Beispiel: starts-with(${phone}, '+254') prüft, ob die Telefonnummer mit der kenianischen Ländervorwahl beginnt.

2. contains(string, substring): Gibt true zurück, wenn string den substring enthält.

   • Beispiel: contains(${email}, '@') prüft, ob eine E-Mail-Adresse ein @-Zeichen enthält.
   • Beispiel: contains(${notes}, 'urgent') löst eine Folgefrage aus, wenn die Notizen “urgent” erwähnen.

3. substring-before(string, needle): Gibt den Teil von string zurück, der vor dem ersten Vorkommen von needle erscheint.

   • Beispiel: substring-before(${full_name}, ' ') extrahiert das erste Wort (Vorname).

4. substring-after(string, needle): Gibt den Teil von string zurück, der nach dem ersten Vorkommen von needle erscheint.

   • Beispiel: substring-after(${email}, '@') extrahiert den Domainteil einer E-Mail-Adresse.

5. normalize-space(string): Entfernt führende und nachfolgende Leerzeichen und reduziert alle internen Leerzeichenfolgen auf ein einzelnes Leerzeichen.

   • Beispiel: normalize-space(${name}) — bereinigt einen Namen, der möglicherweise mit überflüssigen Leerzeichen eingegeben wurde.

6. translate(string, search_chars, replace_chars): Ersetzt jedes Zeichen in string, das in search_chars vorkommt, durch das entsprechende Zeichen in replace_chars. Zeichen in search_chars ohne entsprechendes Zeichen in replace_chars werden gelöscht.

   • Beispiel: translate(${code}, 'abcdefghijklmnopqrstuvwxyz', 'ABCDEFGHIJKLMNOPQRSTUVWXYZ') konvertiert in Großbuchstaben (äquivalent zu upper()).
   • Beispiel: translate(${phone}, ' -()', '') entfernt Leerzeichen, Bindestriche und Klammern aus einer Telefonnummer.

Weitere mathematische Funktionen link

1. floor(number): Gibt die größte ganze Zahl zurück, die kleiner oder gleich number ist (rundet in Richtung negativ unendlich).

   • Beispiel: floor(4.9) = 4, floor(-2.1) = -3

2. ceiling(number): Gibt die kleinste ganze Zahl zurück, die größer oder gleich number ist (rundet in Richtung positiv unendlich).

   • Beispiel: ceiling(4.1) = 5, ceiling(-2.9) = -2

3. random(): Gibt eine zufällige Dezimalzahl zwischen 0,0 (einschließlich) und 1,0 (ausschließlich) zurück. Wird typischerweise in calculate-Feldern verwendet, um zufällige Werte zuzuweisen oder die Fragereihenfolge zu randomisieren.

   • Beispiel: random() → z. B. 0.7341
   • Beispiel: int(random() * 6) + 1 → Zufallszahl 1–6 (Würfelwurf)

4. coalesce(a, b): Gibt a zurück, wenn a nicht leer ist; andernfalls wird b zurückgegeben. Nützlich als Fallback, wenn ein Feld leer sein könnte.

   • Beispiel: coalesce(${preferred_name}, ${full_name}) — bevorzugten Namen verwenden, falls gesetzt, andernfalls auf vollständigen Namen zurückfallen.

5. once(value): Wertet value aus und speichert es, aber nur wenn das aktuelle Feld leer ist. Wenn das Feld bereits einen Wert hat (z. B. zuvor gesetzt wurde), gibt once() den vorhandenen Wert unverändert zurück. Dies verhindert, dass eine Neuberechnung die Benutzereingabe überschreibt.

   • Beispiel: once(today()) in der Spalte default setzt das heutige Datum einmal und aktualisiert es nicht, wenn der Interviewer das Formular erneut öffnet.
   • Beispiel: once(uuid()) generiert eine UUID einmalig und hält sie über Bearbeitungen hinweg stabil.

Geo-Funktionen link

1. area(geoshape_value): Berechnet die Fläche in Quadratmetern, die von einem Geoshape (Polygon)-Wert eingeschlossen wird.

   • Der Parameter ist ein Geoshape-Feldwert im Format lat1 lon1 0 0; lat2 lon2 0 0; ...
   • Beispiel: area(${field_boundary}) — Berechnung der Fläche eines vermessenen Feldes in m².
   • Beispiel: round(area(${field_boundary}) div 10000, 2) — Umrechnung in Hektar.

2. distance(coordinates): Berechnet die Gesamtweglänge in Metern eines Geotrace (Linie) oder den Abstand zwischen zwei Geopunkten.

   • Für einen Geotrace: distance(${route}) gibt die Gesamtweglänge in Metern zurück.
   • Für zwei Geopunkte: distance(concat(${point_a}, ' ', ${point_b})) gibt den Abstand zwischen ihnen zurück.
   • Beispiel: round(distance(${road_trace}) div 1000, 3) — Straßenlänge in Kilometern.

Validierungsfunktionen link

1. regex(value, pattern): Gibt true zurück, wenn value dem regulären Ausdruck pattern entspricht. In der Spalte constraint für musterbasierte Validierung verwenden.

   • Das Muster verwendet Standard-Regex-Syntax (POSIX ERE-Teilmenge).
   • Beispiel: regex(., '^[0-9]{10}$') — eine 10-stellige Zahl validieren.
   • Beispiel: regex(., '^[A-Z]{2}[0-9]{6}$') — Reisepassnummer-Format validieren (2 Großbuchstaben gefolgt von 6 Ziffern).
   • Beispiel: regex(., '^[^@]+@[^@]+\.[^@]{2,}$') — grundlegende E-Mail-Format-Prüfung.

2. checklist(min, max, v1, v2, ...): Wertet eine Liste boolescher Ausdrücke aus und gibt true zurück, wenn die Anzahl der true-Werte zwischen min und max liegt (einschließlich). Übergeben Sie -1 für min oder max, um diese Grenze zu überspringen.

   • Beispiel: checklist(2, 3, ${q1} = 'yes', ${q2} = 'yes', ${q3} = 'yes') — gilt, wenn genau 2 oder 3 der drei Bedingungen wahr sind.
   • Beispiel: checklist(1, -1, ${smoke_alarm}, ${fire_ext}, ${emergency_plan}) — mindestens eine Sicherheitsmaßnahme muss wahr sein.

3. weighted-checklist(min, max, v1, w1, v2, w2, ...): Wie checklist(), aber jeder Wert hat ein Gewicht. Die Summe der Gewichte für true-Werte muss zwischen min und max liegen.

   • Beispiel: weighted-checklist(10, -1, ${has_toilet}, 4, ${has_sink}, 3, ${has_shower}, 5) — die Summe der Gewichte vorhandener Einrichtungen muss mindestens 10 betragen.

Hilfsfunktionen link

1. uuid(): Generiert eine zufällige UUID (RFC 4122 v4-Format) als Zeichenkette.

   • Beispiel: uuid() → 'a3f8b2c1-4d5e-6f7a-8b9c-0d1e2f3a4b5c'
   • Wird typischerweise mit once() verwendet, um eine stabile eindeutige ID zu generieren: once(uuid())

2. version(): Gibt den Wert des version-Attributs des Formulars zurück, wie im settings-Arbeitsblatt festgelegt.

   • Beispiel: version() → '3.1'
   • Nützlich in calculate-Feldern, um die Formularversion in exportierten Daten einzubetten.

3. position(): Gibt bei Aufruf innerhalb einer Wiederholungsgruppe den 1-basierten Index der aktuellen Wiederholungsinstanz zurück.

   • Beispiel: position() in der ersten Instanz gibt 1 zurück, in der zweiten 2 usw.
   • Siehe auch: index() (Alias), indexed-repeat() für die Referenzierung von Wiederholungswerten von außerhalb der Gruppe.

4. thousandsep(length, separator, value): Formatiert eine Zahl mit einem Tausendertrennzeichen. length ist die minimale Gesamtlänge der Zeichenkette (mit Leerzeichen aufgefüllt, wenn kürzer), separator ist das zu verwendende Zeichen (z. B. ','), und value ist die zu formatierende Zahl.

   • Beispiel: thousandsep(0, ',', 1234567) → '1,234,567'
   • Beispiel: thousandsep(0, '.', ${income}) → formatiert das Einkommen mit Punkt als Tausendertrennzeichen.

5. substr-jsonpath(value, jsonpath): Extrahiert einen Teilstring aus einer JSON-Zeichenkette mithilfe eines JSONPath-Ausdrucks.

   • Beispiel: substr-jsonpath(${api_response}, '$.data.name') — das Feld name aus einer in api_response gespeicherten JSON-Zeichenkette extrahieren.
   • Wird typischerweise zusammen mit callapi() verwendet, um spezifische Werte aus API-Antworten zu extrahieren.