Funkcja pulldata("@javascript") umożliwia wywołanie funkcji JavaScript, dzięki czemu można korzystać z zaawansowanych technik i logiki, na które nie pozwalają same formularze XLSForm.
Niestandardowe pliki JavaScript muszą być zapisane w folderze o nazwie scripts w katalogu ankiety.
Podstawowa składnia
Istnieje możliwość wywoływania niestandardowych funkcji JavaScript zwracających wartości. W celu wywoływania niestandardowych funkcji JavaScript należy używać następującej składni funkcji pulldata("@javascript"):
pulldata("@javascript", "yourJSFile.js", "yourFunction", "parameter1", "parameter2")
W powyższym przykładzie funkcja JavaScript oczekuje dwóch parametrów, ale można dodać dowolną ich liczbę.
Jako parametrów funkcji pulldata("@javascript") można używać innych pytań w ankiecie. W następującym przykładzie odpowiedź na pytanie project_code została przekazana do funkcji projectLookup:
pulldata("@javascript", "projects.js", "projectLookup", ${project_code})
Notatka:
Skonfigurowanie punktu geograficznego, śladu geograficznego lub kształtu geograficznego jako parametrów funkcji pulldata("@javascript") nie jest obsługiwane w aplikacji Survey123 Studio ani Survey123 Mobile.
Za pomocą funkcji pulldata("@json") można wyodrębnić konkretne wartości z obiektu JSON wygenerowanego przez funkcję JavaScript. Więcej informacji zawiera sekcja Pobieranie wartości z formatu JSON.
Czasami, zwłaszcza w przypadku używania języka JavaScript do uzyskiwania dostępu do usług internetowych i zabezpieczonych usług ArcGIS, może być potrzebny dostęp do urządzenia i właściwości użytkownika. Funkcja pulldata("@property") umożliwia wyodrębnianie informacji dotyczących urządzeń, z których są przesyłane odpowiedzi na ankietę, oraz zalogowanych użytkowników, którzy przesłali te odpowiedzi. Więcej informacji na ten temat zawiera sekcja Właściwości urządzenia, użytkownika i ankiety.
Wskazówka:
W przypadku zapytań przestrzennych i atrybutowych w warstwie obiektowej ArcGIS rozważ użycie funkcji pulldata("@layer") zamiast pulldata("@javascript"). Składnia funkcji pulldata("@layer") jest przeznaczona specjalnie dla zapytań o warstwę obiektową i jest obsługiwana w przypadku ankiet publicznych. Więcej informacji zawiera temat Zapytanie o warstwę obiektową.
Powtórzenia
Notatka:
W tej sekcji opisano funkcje, które są dostępne tylko w aplikacji Survey123 Connect i aplikacji terenowej Survey123. Funkcje te nie są dostępne w aplikacji Survey123 Studio ani Survey123 Mobile.
Istnieje możliwość przekazywania do funkcji JavaScript wszystkich wartości z powtórzenia. Funkcja pulldata("@javascript") obsługuje dwa typy implementacji pobierania wartości z powtórzeń. Użycie jednego z nich zależy od tego, czy funkcja JavaScript ma działać na jednym polu, czy wielu polach w powtórzeniu.
Jeśli jako parametr funkcji przekazywane jest pytanie z powtórzenia, funkcja JavaScript otrzymuje tablicę wartości z określonego pytania w następujący sposób:
pulldata("@javascript", "yourJSFile.js", "yourFunction", ${question1})
Jeśli jako parametr funkcji przekazywana jest nazwa powtórzenia, funkcja JavaScript otrzymuje parametr w postaci tablicy wierszy wszystkich wartości w powtórzeniu w następujący sposób:
pulldata("@javascript", "yourJSFile.js", "yourFunction", ${repeat1}, "question1")
W każdym z tych przypadków zwracany jest obiekt JSON, którego właściwościami są poszczególne pytania.
Notatka:
Dostęp do wartości w powtórzeniach przy użyciu pulldata("@javascript") nie jest obsługiwany w aplikacji internetowej Survey123. Wartości związane z pojedynczym pytaniem w powtórzeniu można zbierać w aplikacji internetowej, korzystając z funkcji join() do przekształcenia listy wartości w ciąg znakowy rozdzielany znakami, a następnie dzieląc te wartości za pomocą funkcji JavaScript.
Od aplikacji Survey123 w wersji 3.14 puste wartości przekazane za pomocą funkcji JavaScript mogą teraz zwracać wartość undefined albo null. Ze względu na to funkcje JavaScript należy teraz pisać z uwzględnieniem możliwości wystąpienia wartości undefined.
Znane ograniczenia
Poniżej przedstawiono znane ograniczenia związane z użyciem funkcji JavaScript w formularzach ankiet:
- Model DOM (Document Object Model) nie jest obsługiwany.
- Środowiska, takie jak JQuery, Ember i Angular, nie są obsługiwane.
- Nie można uzyskać dostępu do plików lokalnych.
- Wywołania asynchroniczne nie są obsługiwane.
- Funkcje JavaScript są obsługiwane tylko w formularzach wypełnianych przez użytkowników z tej samej instytucji co autor formularza.
- Funkcje JavaScript nie są obsługiwane w przypadku ankiet publicznych.
- Funkcji pulldata("@javascript") nie można wywoływać wewnątrz funkcji pulldata("@json") w aplikacji internetowej Survey123.
Narzędzia skryptu
Notatka:
W tej sekcji opisano funkcje, które są dostępna tylko w aplikacji Survey123 Connect. Te funkcje nie są dostępne w aplikacji Survey123 Studio.
Operacje edytowania funkcji JavaScript i zarządzania nimi można przeprowadzać na karcie Skrypty aplikacji Survey123 Connect. Na tej karcie można utworzyć plik JavaScript, przejrzeć kod i przetestować funkcję. Ta karta nie zastępuje w pełni zintegrowanego środowiska programistycznego (IDE), które może zapewnić weryfikację kodu i analizę najlepszych praktyk, aby pomóc w opracowywaniu funkcji JavaScript, ale ta karta jest przeznaczona do pomocy w integracji tych funkcji w aplikacji Survey123.
W menu karty Skrypty aplikacji Survey123 Connect dostępne są następujące narzędzia:
- Pliki skryptów — wyświetlenie wszystkich plików JavaScript w folderze scripts ankiety. Wybierz plik do wyświetlenia lub edycji.
- Otwórz folder skryptów — uruchomienie przeglądarki plików w lokalizacji folderu scripts ankiety.
- Nowy plik skryptu — utworzenie pliku skryptu w folderze scripts ankiety. Wpisz nazwę pliku i kliknij przycisk Utwórz.
- Wybierz funkcję — wyróżnienie pierwszej funkcji w otwartym pliku i udostępnienie parametrów do testowania.
- Zapisz — zapisanie zmian wprowadzonych w otwartym pliku.
- Uruchom edytor zewnętrzny — uruchomienie domyślnego środowiska JavaScript IDE z otwartym plikiem.
Kliknij narzędzie Wybierz funkcję, aby przetestować działanie pierwszej funkcji w pliku, wpisując wartości poszczególnych parametrów i przeglądając wynik. Po zakończeniu pracy z funkcją możesz skopiować przedstawioną tutaj instrukcję pulldata i wkleić ją do formularza XLSForm. Użytkownik zalogowany w instytucji może kliknąć prawym przyciskiem myszy dowolny parametr, a następnie w razie potrzeby kliknąć opcję Wklej token.