Mit der Funktion pulldata("@javascript") lassen sich JavaScript-Funktionen aufrufen. Auf diese Weise können Sie erweiterte Techniken und Logik verwenden, die über die Möglichkeiten von XLSForm allein hinausgehen.
Sie sind in der Lage, JavaScript-Funktionen auf der Registerkarte Skripte von Survey123 Connect zu verwalten und zu bearbeiten. Auf dieser Registerkarte können Sie eine JavaScript-Datei erstellen, den Code überprüfen und die Funktion testen. Diese Registerkarte ist kein vollständiger Ersatz für eine IDE (Integrated Development Environment, integrierte Entwicklungsumgebung), die Code-Validierung und Best-Practice-Analysen bereitstellen kann, um zur Entwicklung von JavaScript-Funktionen beizutragen. Die Registerkarte ist als Hilfe bei der Integration dieser Funktionen in Survey123 gedacht.
Skriptwerkzeuge in Survey123 Connect
Die folgenden Werkzeuge sind im Menü der Registerkarte Skripte von Survey123 Connect verfügbar:
- Skriptdateien: Zeigt alle JavaScript-Dateien an, die sich im Ordner Scripts eines Survey befinden. Wählen Sie eine Datei aus, um sie anzuzeigen und zu bearbeiten.
- Skriptordner öffnen: Öffnet den Datei-Browser mit dem Pfad des Ordners Scripts eines Survey.
- Neue Skriptdatei: Erstellt eine Skriptdatei im Ordner Scripts eines Survey. Geben Sie den Dateinamen ein, und klicken Sie auf Erstellen.
- Funktion auswählen: Hebt die erste Funktion in der geöffneten Datei hervor und zeigt die Parameter für das Testen an.
- Speichern: Speichert Änderungen an der geöffneten Datei.
- Externen Editor starten: Startet die standardmäßige JavaScript-IDE des Systems mit der geöffneten Datei.
Klicken Sie auf das Werkzeug Funktion auswählen, um das Verhalten der ersten Funktion in der Datei zu testen, indem Sie Werte für jeden Parameter eingeben und die Ausgabe anzeigen. Sobald Sie mit der Funktion fertig sind, können Sie die angezeigte pulldata-Anweisung kopieren und in XLSForm einfügen. Wenn Sie bei Ihrer Organisation angemeldet sind, klicken Sie mit der rechten Maustaste auf die Parameter, und klicken Sie dann auf Token einfügen, sofern erforderlich.
Hinweis:
Grundlegende Syntaxfehler werden auf der Registerkarte Skripte mit einem Fehlerindikator neben der Zeilennummer angezeigt. Die Fehlerbehandlung muss in die JavaScript-Funktion implementiert werden. Die Konsolenausgabe wird auf der Registerkarte Skripte angezeigt. Indem Sie Konsolenmeldungen in die Funktion aufnehmen, können Sie also zusammen mit der Ausgabe Fehler, Warnungen und Informationsmeldungen einblenden.Grundlegende Syntax
Sie können benutzerdefinierte JavaScript-Funktionen zur Rückgabe von Werten aufrufen. Verwenden Sie die folgende Syntax, um benutzerdefinierte JavaScript-Funktionen mit der Funktion pulldata("@javascript") aufzurufen:
pulldata("@javascript", "yourJSFile.js", "yourFunction", "parameter1", "parameter2")
Sie müssen die benutzerdefinierten JavaScript-Dateien in einem Ordner namens "scripts" im Verzeichnis "survey" speichern. Im obigen Beispiel erwartet die JavaScript-Funktion zwei Parameter, Sie können jedoch eine beliebige Anzahl von Funktionsparametern hinzufügen.
Mit der Funktion pulldata("@json") können Sie bestimmte Werte aus einem JSON-Objekt extrahieren, das mit einer JavaScript-Funktion erzeugt wurde. Weitere Informationen finden Sie unter Abrufen eines Wertes aus JSON-Code.
In einigen Fällen, insbesondere bei Verwendung von JavaScript für den Zugriff auf Web-Services und gesicherte ArcGIS-Services, benötigen Sie möglicherweise Zugriff auf Geräte- und Benutzereigenschaften. Mit der Funktion pulldata("@property") können Sie Informationen zu den Geräten, mit denen Survey-Antworten übermittelt werden, sowie zu den angemeldeten Benutzern, die die Antworten übermitteln, extrahieren. Weitere Informationen finden Sie unter Geräte- und Benutzereigenschaften.
Tipp:
Bei Attribut- und räumlichen Abfragen für ArcGIS-Feature-Layer sollten Sie in Erwägung ziehen, die Funktion pulldata("@layer") anstelle von pulldata("@javascript") zu verwenden. Die Syntax pulldata("@layer") wurde speziell für Feature-Layer-Abfragen entwickelt und wird für öffentliche Surveys unterstützt. Weitere Informationen finden Sie unter Durchführen einer Abfrage für einen Feature-Layer.
Wiederholungen
Sie haben die Möglichkeit, alle Werte innerhalb von Wiederholungen an die JavaScript-Funktionen zu übergeben. Die Funktion pulldata("@javascript") unterstützt zwei Arten der Implementierung zum Abrufen der Werte aus einer Wiederholung. Welche jeweils verwendet wird, ist abhängig davon, ob die JavaScript-Funktion mit einem oder vielen Feldern in einer Wiederholung interagieren soll.
Wenn eine Frage aus einer Wiederholung als Funktionsparameter übergeben wird, erhält die JavaScript-Funktion ein Array aus Werten von der angegebenen Frage:
pulldata("@javascript", "yourJSFile.js", "yourFunction", ${question1})
Wenn ein Wiederholungsname als Funktionsparameter übergeben wird, erhält die JavaScript-Funktion den Parameter als ein Array aus Zeilen mit allen Werten in der Wiederholung:
pulldata("@javascript", "yourJSFile.js", "yourFunction", ${repeat1}, "question1")
Daraus wird jeweils ein JSON-Objekt mit einzelnen Fragen als Eigenschaften in diesem Objekt erzeugt.
Hinweis:
Der Zugriff auf Werte in Wiederholungen mit pulldata("@javascript") wird in der Survey123-Web-App nicht unterstützt. Sie können Werte für eine einzelne Frage in einer Wiederholung in der Web-App erfassen, indem Sie join() verwenden, um die Liste der Werte in eine durch Zeichen getrennte Zeichenfolge zu konvertieren, und die Werte in der JavaScript-Funktion teilen.
Ab Survey123 Version 3.14 können leere Werte, die über eine JavaScript-Funktion übergeben werden, entweder undefined oder null zurückgeben. Aus diesem Grund müssen Sie JavaScript-Funktionen so schreiben, dass die Möglichkeit eines undefined-Wertes berücksichtigt wird.
Bekannte Einschränkungen
Folgende Einschränkungen sind bei der Verwendung von JavaScript-Funktionen in Survey-Formularen bekannt:
- DOM (Document Object Model) wird nicht unterstützt.
- Umgebungen wie JQuery, Ember und Angular werden nicht unterstützt.
- Sie können nicht auf lokale Dateien zugreifen.
- Asynchrone Aufrufe werden nicht unterstützt.
- JavaScript-Funktionen werden nur in Formularen unterstützt, die von Benutzern aus derselben Organisation wie der Autor des Formulars ausgefüllt werden.
- JavaScript-Funktionen werden für öffentliche Surveys nicht unterstützt.
- Eine pulldata("@javascript")-Funktion kann auf der pulldata("@json")-Web-App nicht innerhalb einer Survey123-Funktion aufgerufen werden.