pulldata("@javascript") 関数を使用して JavaScript 関数を呼び出すことで、XLSForm だけでは使用できない高度な手法やロジックを使用することができます。
Survey123 Connect の [スクリプト] タブで JavaScript 関数の管理と編集を行うことができます。 このタブでは、JavaScript ファイルを作成し、コードを確認し、関数をテストすることができます。 このタブは、JavaScript 関数の開発に役立つコードの検証やベスト プラクティス解析が提供される統合開発環境 (IDE) の完全な置き換えになるものではありませんが、Survey123 におけるこれらの関数の統合を支援するように設計されています。
Survey123 Connect のスクリプト ツール
Survey123 Connect の [スクリプト] タブのメニューで使用できるツールを次に示します。
- [スクリプト ファイル] - 調査の Scripts フォルダーにあるすべての JavaScript ファイルを表示します。 表示、編集するファイルを選択します。
- [スクリプト フォルダーを開く] - 調査の Scripts フォルダーの場所でファイル ブラウザーを起動します。
- [新しいスクリプト ファイル] - 調査の Scripts フォルダーにスクリプト ファイルを作成します。 ファイル名を入力して [作成] をクリックします。
- [関数の選択] - 開いたファイルの最初の関数をハイライトし、テストのためのパラメーターを提示します。
- [保存] - 開いたファイルに変更内容を保存します。
- [外部エディターの起動] - 開いたファイルでシステムのデフォルトの JavaScript IDE を起動します。
[関数の選択] ツールをクリックして、各パラメーターに値を入力して結果を表示することで、ファイルの最初の関数の挙動をテストします。 関数による作業が終了したら、ここに提示する pulldata ステートメントをコピーして XLSForm に貼り付けることができます。 組織サイトにサイン インしている場合は、必要に応じて、任意のパラメーターを右クリックして [トークンの貼り付け] をクリックします。
注意:
[スクリプト] タブには基本的な構文エラーが表示され、行番号の横にエラー インジケーターが示されます。 JavaScript 関数の内部にはエラー処理を実装する必要があります。 [スクリプト] タブにはコンソール出力が表示されるので、関数にコンソール メッセージを含めることで、エラー、警告、情報メッセージを出力と一緒に表示することができます。基本的な構文
カスタム JavaScript 関数を呼び出して値を返すことができます。 次の構文を使用し、pulldata("@javascript") 関数を使用したカスタム JavaScript 関数を呼び出すことができます。
pulldata("@javascript", "yourJSFile.js", "yourFunction", "parameter1", "parameter2")
カスタム JavaScript ファイルは、調査ディレクトリの scripts フォルダーに格納する必要があります。 上記の例で、JavaScript 関数は 2 つのパラメーターを想定していますが、任意の数の関数パラメーターを追加することができます。
pulldata("@json") 関数を使用すると、JavaScript 関数で生成された JSON オブジェクトから特定の値を抽出できます。 詳細については、「JSON からの値の取得」をご参照ください。
特に、JavaScript を使用して Web サービスやセキュリティ保護された ArcGIS サービスにアクセスする場合、デバイスとユーザーのプロパティにアクセスする必要がある場合があります。 pulldata("@property") 関数を使用して、調査の回答を送信したデバイスと、回答を送信したサインイン済みユーザーに関する情報を抽出できます。 詳細については、「デバイスとユーザー プロパティ」をご参照ください。
ヒント:
ArcGIS フィーチャ レイヤーでの空間検索と属性検索では、pulldata("@javascript") の代わりに pulldata("@layer") 関数の使用を検討してください。 pulldata("@layer") 構文はフィーチャ レイヤーのクエリ専用として設計されており、パブリックな調査でサポートされています。 詳細については、「フィーチャ レイヤーのクエリ」をご参照ください。
繰り返し
繰り返し全体のすべての値を JavaScript 関数に渡すことができます。 pulldata("@javascript") 関数では、2 つの実装方法で繰り返しから値を取得できます。 使用する実装方法は、JavaScript 関数で繰り返し内の 1 つのフィールドを操作するか、複数のフィールドと操作するかによって異なります。
繰り返しの質問が関数パラメーターとして渡された場合、JavaScript 関数は次のようにして、指定した質問から値の配列を受け取ります。
pulldata("@javascript", "yourJSFile.js", "yourFunction", ${question1})
繰り返し名が関数パラメーターとして渡された場合、JavaScript 関数は次のようにして、繰り返し内のすべての値から構成される行の配列としてパラメーターを受け取ります。
pulldata("@javascript", "yourJSFile.js", "yourFunction", ${repeat1}, "question1")
これらの各パラメーターが、プロパティとして個別の質問を含む JSON オブジェクトを生成します。
注意:
pulldata("@javascript") を使用して繰り返し内の値にアクセスすることは、Survey123 Web アプリではサポートされていません。join() を使用して、値のリストを区切り文字で区切られた文字列に変換し、JavaScript 関数内で値を分割することで、Web アプリで繰り返し内の 1 つの質問の値を収集することができます。
Survey123 バージョン 3.14 以降、JavaScript 関数に渡された空の値は undefined または null を返すことができるようになりました。 このため、undefined 値の可能性に対応するために、JavaScript 関数を記述する必要があります。
既知の制限
調査フォームで JavaScript 関数を使用する際は、次の既知の制限が存在します。
- DOM (Document Object Model) はサポートされていません。
- JQuery、Ember、Angular などのフレームワークはサポートされていません。
- ローカル ファイルにアクセスできません。
- 非同期の呼び出しはサポートされていません。
- JavaScript 関数は、フォームの作成者と同じ組織内のユーザーが入力したフォームでのみサポートされます。
- JavaScript 関数はパブリックな調査ではサポートされていません。
- Survey123 Web アプリの pulldata("@json") 関数内で、pulldata("@javascript") 関数を呼び出すことはできません。