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.
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.
Narzędzia skryptu w aplikacji Survey123 Connect
W menu karty Skrypty aplikacji Survey123 Connect dostępne są następujące narzędzia:
- Pliki skryptów — wyświetlenie wszystkich plików JavaScript znajdujących się 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.
Notatka:
Podstawowe błędy składni są pokazane na karcie Skrypty, gdzie podany jest wskaźnik błędu obok numeru wiersza. Obsługa błędów musi być zaimplementowana wewnątrz funkcji JavaScript. Wynik konsoli jest wyświetlany na karcie Skrypty, więc włączając komunikaty konsoli do funkcji, możesz zobaczyć błędy, ostrzeżenia i komunikaty informacyjne wyświetlane wraz z wynikiem.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")
Niestandardowe pliki JavaScript muszą być zapisane w folderze o nazwie scripts w katalogu ankiety. W powyższym przykładzie funkcja JavaScript oczekuje dwóch parametrów, ale można dodać dowolną ich liczbę.
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 zawiera sekcja Właściwości urządzenia i użytkownika.
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
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.