Formuły

Dzięki formułom można tworzyć lepsze formularze w aplikacji ArcGIS Survey123.

W wyrażeniu należy zawsze odwoływać się do poprzednich pytań przy użyciu formatu ${field_name}.

Operatory

W aplikacji Survey123 obsługiwane są następujące operatory:

Operator	Opis	Przykład
.	Bieżąca odpowiedź	.=1
+	Dodawanie	${question_one} + 4
-	Odejmowanie	${question_one} - 4
*	Mnożenie	${question_one} * 4
div	Dzielenie	${question_one} div 4
=	Równy	${price}=9.80
!=	Nierówne	${price}!=9.80
<	Mniejsze niż	${price}<9.80
<=	Mniejsze lub równe	${price}<=9.80
>	Większe niż	${price}>9.80
>=	Większe lub równe	${price}>=9.80
and	I	${price}>9.00 and ${price}<9.90
mod	Dzielenie z resztą (reszta z dzielenia)	${question_one} mod ${question_two}
or	Lub	${price}=9.80 or ${price}=9.70

Funkcje

W aplikacji Survey123 są obsługiwane następujące funkcje:

Funkcja	Opis	Przykład
boolean(question, expression, or value)	Zwraca wartość prawda (true), jeśli została podana wartość inna niż null. Zalecane jest użycie funkcji boolean-from-string() zamiast tej funkcji. Uwaga: Ta funkcja w aplikacji internetowej Survey123 zawsze zwraca wartość prawda (true). Inne możliwości można znaleźć w sekcji Wartości puste.	boolean(${question_one})
boolean-from-string()	Zwraca wartość prawda (true), jeśli został podany ciąg znakowy „true” lub „1”. W przeciwnym razie zwracana jest wartość fałsz (false).	boolean-from-string(${question_one})
coalesce(value1, value2)	Zwraca pierwszą wartość niepustą. Ta funkcja obsługuje tylko dwie wartości.	coalesce(${question_one}, ${question_two})
concat(value1, value2, …)	Zwraca konkatenację ciągów znakowych.	concat(${question_one}, ' and ', ${question_two})
contains(string, substring)	Zwraca wartość prawda (true), jeśli dany ciąg znakowy zawiera określony podciąg.	contains(${question_one}, 'red')
count(repeat)	Zwraca liczbę odpowiedzi na dane pytanie w powtórzeniach. Więcej informacji na ten temat zawiera sekcja Funkcje agregujące. Notatka: W aplikacji terenowej Survey123 tę funkcję można umieścić w powtórzeniu lub poza nim. Jeśli funkcja ma być używana w aplikacji internetowej Survey123, musi zostać umieszczona poza powtórzeniem. Wartość zliczenia spoza powtórzenia może być przywoływana w obliczeniu wewnątrz powtórzenia.	count(${question})
count-selected(question)	Zwraca liczbę wybranych odpowiedzi dla pytań typu select_one (wybierz jedną) i select_multiple (wybierz wiele). Ta funkcja zwraca również liczbę dołączonych plików dla pytań typu image (obraz), audio (dźwięk) oraz file (plik) z wyglądem multiline (wielowierszowy).	count-selected(${question_one})
date(question, expression, or value)	Przekształca liczbę lub ciąg znakowy w obiekt daty (bez czasu).	date('2017-05-28T04:39:02+10:00')
date-time(question, expression, or string)	Przekształca liczbę lub ciąg znakowy w obiekt daty.	date-time('2017-05-28T04:39:02+10:00')
decimal-date-time(question, expression, or string)	Przekształca obiekt daty w liczbę dziesiętną reprezentującą datę i czas.	decimal-date-time(${date_question})
decimal-time(question, expression, or string)	Przekształca obiekt czasu w liczbę reprezentującą wartość ułamkową pory dnia w strefie czasowej urządzenia.	decimal-time(${time_question})
ends-with(string, substring)	Zwraca wartość prawda (true), jeśli dany ciąg znakowy kończy się określonym podciągiem.	ends-with(${question_one}, 'hand.')
false()	Fałsz	false()
format-date()	Dopasowuje istniejącą wartość daty lub czasu do zdefiniowanego formatu.	format-date(${previous_time}, '%H:%M')
if(condition, a, b)	Jeśli warunek przyjmuje wartość prawda (true), zwraca a, w przeciwnym razie zwraca b.	if(selected(${question_one}, 'yes') and selected(${question_two}, 'yes'), 'yes', 'no')
indexed-repeat(pytanie, powtórzenie, numer indeksu)	Zwraca wartość z konkretnego pytania w rekordzie powtórzeń. Więcej informacji zawiera temat Powtórzenia.	indexed-repeat(${room_no}, ${floor}, 3)
int(question, expression, or value)	Służy do przekształcania do liczby całkowitej. Przekształcenie zależy od typu danych. Notatka: Jeśli ta funkcja jest pusta, zwróci wartość NaN, a pytanie pozostanie puste.	int(${question_one})
join(separator, question)	Łączy wszystkie odpowiedzi na dane pytanie w powtórzeniu, rozdzielając je podanym separatorem.	join(',', ${question_in_repeat})
jr:choice-name(choice_name, 'question')	Używana na potrzeby pytań select_one. Zwraca etykietę powiązaną z nazwą możliwości wyboru w danym pytaniu. Należy pamiętać, że pytanie musi być ujęte w cudzysłów.	jr:choice-name(${select_one}, '${select_one}')
	Używana na potrzeby pytań select_multiple. Zwraca etykietę powiązaną z nazwą możliwości wyboru w danym pytaniu. Należy użyć funkcji selected-at() w celu wyodrębnienia etykiet poszczególnych odpowiedzi. Należy pamiętać, że pytanie musi być ujęte w cudzysłów.	jr:choice-name(selected-at(${select_multiple}, 3), '${select_multiple}')
max(value1, value2, ...)	Zwraca wartość maksymalną w danym zakresie lub w odpowiedzi na jedno pytanie w powtórzeniach.	max(${question_one}, ${question_two})
min(value1, value2, ...)	Zwraca wartość minimalną w danym zakresie lub w odpowiedzi na jedno pytanie w powtórzeniach.	min(${question_one}, ${question_two})
not(expression)	Zwraca wartość fałsz (false), jeśli wyrażenie zwróciłoby wartość prawda (true), a wartość prawda (true), jeśli wyrażenie zwróciłoby wartość fałsz (false).	not(selected(., 'yes'))
now()	Zwraca datownik tej chwili. Ta funkcja jest używana w pytaniach typu time (czas) oraz dateTime (data i czas). Zachowuje się tak samo jak funkcja today() w pytaniach typu date (data).	now()
number(question, expression, or value)	Służy do przekształcania do liczby. Przekształcenie zależy od typu danych. Notatka: Jeśli ta funkcja jest pusta, zwróci wartość NaN, a pytanie pozostanie puste.	number(${question_one})
once()	Jeśli pytanie ma już wartość, zwraca tę istniejącą wartość. Ta funkcja jest przydatna podczas korzystania z funkcji random() lub uuid() w pytaniu powtarzanym w celu zapewnienia, że wartość nie zmienia się podczas przeglądania powtarzanych rekordów w formularzu.	once(uuid())
position(..)	Zwraca indeks bieżącego rekordu w powtórzeniu. Więcej informacji zawiera temat Powtórzenia.	position(..)
pulldata()	Zwraca wartość z zewnętrznego pliku CSV. Więcej informacji zawiera sekcja Pobieranie wartości z pliku CSV.	pulldata('users', 'email', 'name', ${respondent_name})
pulldata("@exif")	Zwraca wartość z metadanych EXIF w obrazie. Więcej informacji na ten temat zawiera sekcja Wyodrębnianie metadanych obrazu.	pulldata("@exif", ${photo}, "GpsLatitude")
pulldata("@geopoint")	Zwraca wartość z pytania typu geopoint (punkt geograficzny). Więcej informacji na ten temat zawiera sekcja Wyodrębnianie wartości punktu geograficznego.	pulldata("@geopoint", ${location}, "horizontalAccuracy")
pulldata("@javascript")	Uruchamia funkcję JavaScript w formularzu i zwraca wynik. Więcej informacji na ten temat zawiera sekcja Funkcje JavaScript w formularzach ankiety.	pulldata("@javascript", "functions.js", "uniqueID", ${buildings})
pulldata("@json")	Zwraca wartość z obiektu JSON. Więcej informacji zawiera sekcja Pobieranie wartości z formatu JSON.	pulldata("@json", ${json_output}, "attributes.ZIP_CODE")
pulldata("@layer")	Wysyła zapytanie do warstwy obiektowej, tabeli obiektów lub usługi mapowej ArcGIS z włączoną obsługą zapytań i zwraca wynik. Więcej informacji zawiera temat Zapytanie o warstwę obiektową.	pulldata("@layer", "getRecordAt", "https://services.arcgis.com/P3ePLMYs2RVChkJx/arcgis/rest/services/World_Time_Zones/FeatureServer/0", ${location})
pulldata("@property")	Zwraca informacje na temat zalogowanego użytkownika lub urządzenia. Więcej informacji zawiera sekcja Właściwości urządzenia i użytkownika.	pulldata("@property", 'username')
random()	Zwraca wartość losową z zakresu od 0 (włącznie) do 1 (wyłącznie).	random()
regex()	Stosuje wyrażenie regularne względem danych wejściowych pytania. Zwraca wartość true (prawda) w przypadku zgodności ze wzorcem. Więcej informacji można znaleźć w sekcji Wyrażenia regularne.	regex(., '^\d{5}$')
selected(pytanie, wartość)	Sprawdza, czy wybrano odpowiedź. Ta funkcja jest używana na potrzeby pytań select_one (wybierz jedną) i select_multiple (wybierz wiele).	selected(${question_one}, 'a')
selected-at(question, number)	Używana na potrzeby pytań select_multiple. Zwraca nazwę możliwości wyboru wskazywanej przez daną liczbę wśród wybranych możliwości wyboru (począwszy od zera), na przykład wartość '2' spowoduje zwrócenie trzeciej spośród wybranych możliwości wyboru.	selected-at(${question_one}, 2)
starts-with(string, substring)	Zwraca wartość prawda (true), jeśli dany ciąg znakowy rozpoczyna się określonym podciągiem.	starts-with(${question_one}, 'The')
string(question, expression, or value)	Służy do przekształcania do ciągu znakowego. Przekształcenie zależy od typu danych.	string(${question_one})
string-length(question, expression, or value)	Zwraca długość niepustego ciągu znakowego.	string-length(${question_one})
substr(question, start, end)	Zwraca podciąg znakowy rozpoczynający się od określonego miejsca początkowego i kończący się na znaku o indeksie wynoszącym koniec -1, gdzie początek i koniec są liczone od pozycji 0.	substr(${question_one}, 1, 2)
sum(repeat)	Zwraca sumę wszystkich odpowiedzi na dane pytanie w powtórzeniach. Więcej informacji na ten temat zawiera sekcja Funkcje agregujące. Notatka: W aplikacji terenowej Survey123 tę funkcję można umieścić w powtórzeniu lub poza nim. Jeśli funkcja ma być używana w aplikacji internetowej Survey123, musi zostać umieszczona poza powtórzeniem. Wartość sumy spoza powtórzenia może być przywoływana w obliczeniu wewnątrz powtórzenia.	sum(${question})
today()	Zwraca bieżącą datę, przechowywaną wewnętrznie jako lokalne południe. Ta funkcja jest używana w pytaniach typu date (data).	today()
true()	Prawda	true()
uuid()	Zwraca losowy ciąg znakowy identyfikatora UUID.	uuid()
version()	Zwraca wersję ankiety zdefiniowaną w arkuszu ustawień.	version()

W aplikacji Survey123 są obsługiwane następujące funkcje matematyczne:

Funkcja	Opis	Przykład
acos(wartość)	Zwraca wartość funkcji arcus cosinus.	acos(${question_one})
asin(wartość)	Zwraca wartość funkcji arcus sinus.	asin(${question_one})
atan(wartość)	Zwraca wartość funkcji arcus tangens.	atan(${question_one})
atan2(wartość1, wartość2)	Zwraca wartość funkcji arcus tangens ilorazu wartości.	atan2(${question_one}, ${question_two})
cos(wartość)	Zwraca wartość funkcji cosinus dla kąta wyrażonego w radianach.	cos(${question_one})
sin(wartość)	Zwraca wartość funkcji sinus dla kąta wyrażonego w radianach.	sin(${question_one})
tan(wartość)	Zwraca wartość funkcji tangens dla kąta wyrażonego w radianach.	tan(${question_one})
exp(wartość)	Zwraca wartość naturalną potęgi dla danej wartości.	exp(${question_one})
exp10(wartość)	Zwraca 10 do potęgi określonej przez wartość.	exp10(${question_one})
log(wartość)	Zwraca logarytm naturalny z wartości.	log(${question_one})
log10(wartość)	Zwraca logarytm o podstawie 10 z wartości.	log10(${question_one})
pi()	Zwraca wartość pi.	pi()
pow(wartość, potęga)	Zwraca wartość podniesioną do podanej potęgi.	pow(${question_one}, 3)
round(wartość, miejsca)	Zwraca wartość zaokrągloną.	round(${question_one}, 5)
sqrt(wartość)	Zwraca pierwiastek kwadratowy z wartości.	sqrt(${question_one})

Ograniczenia

Dodanie ograniczenia do pytania w ankiecie powoduje ograniczenie danych wejściowych akceptowanych w odpowiedzi. Może to dotyczyć określonego zakresu liczb, kombinacji liter i liczb lub dopasowania do ogólnego wzorca. W arkuszu kalkulacyjnym wyrażenie ograniczenia jest wprowadzane w polu constraint (ograniczenie), a tekst informacyjny jest wprowadzany w kolumnie constraint_message (komunikat o ograniczeniu) arkusza survey (ankieta). W wyrażeniu ograniczenia dane wejściowe pytania są zawsze reprezentowane przez kropkę.

Na przykład można użyć następującej formuły, aby ograniczyć dane wejściowe, które można wprowadzić w polu typu liczba całkowita, do wyłącznie liczb dodatnich:

.>= 0

Gdy ta formuła jest zastosowana do pola date, uniemożliwia użytkownikowi wprowadzanie wartości wcześniejszych niż bieżąca data:

.>= today()

W ograniczeniach można także używać obliczeń. W ramach tej formuły wykonywane są obliczenia umożliwiające użytkownikom wybieranie dat wyłącznie między dniem dzisiejszym i datą przypadającą za 14 dni:

(.>= today()) and (.<=(today() + (1000 * 60 * 60 * 24 * 14)))

Wskazówka:

Jeśli formuła zawiera wartości dziesiętne z zakresu od -1 do 1, to, aby uniknąć nieoczekiwanych błędów, należy pamiętać o dodaniu zera na początku wartości. Bez zera na początku wartość dziesiętna może zostać pomylona ze znakiem operacji . (lub -.). Na przykład następujące wyrażenie zakończy się błędem:

.> .25 and .< 24.25

Następujące wyrażenie będzie działać w oczekiwany sposób:

.> 0.25 and .< 24.25

Wyrażenia regularne

Wyrażenie regularne to sekwencja znaków używana do dopasowywania wzorców w ciągach znakowych. Jeśli w aplikacji Survey123 wzorzec jest dopasowany, wyrażenie zwraca wartość true (prawda). W przeciwnym razie wyrażenie zwraca wartość false (fałsz).

Za pomocą wyrażeń regularnych można dopasowywać wzorce na wiele sposobów. Można na przykład narzucić poprawnym odpowiedziom dany format lub sprawdzić, czy zawierają one określoną treść. W tym przykładzie odpowiedź na pytanie musi zawierać słowo road:

regex(., 'road')

Kropka używana na początku tych przykładów powoduje, że dane wyrażenie jest stosowane do bieżącego pola. Dodanie w jej miejscu nazwy innego pola powoduje zastosowanie danego wyrażenia regularnego do tego pola, co doskonale sprawdza się w przypadku wyrażeń relevant (odpowiednie). Przecinek jest separatorem oddzielającym definicję pola od wyrażenia.

To wyrażenie regularne sprawdza, czy odpowiedź zawiera tylko słowo road (droga), bez żadnych znaków przed i po tym słowie:

regex(., '^road$')

Przy użyciu wyrażeń regularnych można nadać odpowiedziom na pytanie standardowy format. W tym przykładzie akceptowane są tylko dane wejściowe w postaci pięciocyfrowego kodu pocztowego używanego w USA:

regex(., '^\d{5}$')

W tym przykładzie odpowiedź jest dopasowywana do bieżącego formatu indonezyjskich tablic rejestracyjnych jak na poniższym zdjęciu:

regex(., '^[A-Z]{1,2}\d{4}[A-Z]{2,3}$')

Formaty, których standardy nie są tak restrykcyjne, mogą wymagać zastosowania złożonych wyrażeń regularnych. To wyrażenie regularne używane w aplikacji internetowej Survey123 pozwala wyłącznie na wprowadzenie pól znakowych o formacie adresu e-mail:

regex(., '^(([^<>()\[\]\\.,;:\s@"]+(\.[^<>()\[\]\\.,;:\s@"]+)*)|(".+"))@((\[[0-9]{1,3}\.[0-9]{1,3}\.[0-9]{1,3}\.[0-9]{1,3}])|(([a-zA-Z\-0-9]+\.)+[a-zA-Z]{2,}))$')

Ta modyfikacja powyższego wyrażenia ogranicza dane wejściowe w celu dopasowania do formatu adresu e-mail przy przyjmowaniu znaków spoza alfabetu angielskiego.

regex(., '^(([^<>()\[\]\\.,;:\s@"]+(\.[^<>()\[\]\\.,;:\s@"]+)*)|(".+"))@((\[[0-9]{1,3}\.[0-9]{1,3}\.[0-9]{1,3}\.[0-9]{1,3}])|(([a-zA-Z\u0400-\uffff\-0-9]+\.)+[a-zA-Z\u0400-\uffff]{2,}))$')

Ten przykład, w którym także wykorzystywane jest wyrażenie regularne z aplikacji internetowej Survey123, ilustruje ograniczenie wartości pola wyłącznie do odpowiedzi zgodnych z formatem adresu internetowego:

regex(., '^((https?|ftps?)\://|)(((?:(?:[\da-zA-Z](?:[-\da-zA-Z]{0,61}[\da-zA-Z])?)\.)+(?:[a-zA-Z](?:[-\da-zA-Z]{0,61}[\da-zA-Z])?)\.?)|localhost)(\:\d+)?(/(?:[^?#\s/]+/)*(?:[^?#\s/]+(?:\?[^?#\s/]*)?(?:#[A-Za-z][\w.:-]*)?)?)?')

Więcej informacji o wyrażeniach regularnych można znaleźć w dokumentacji Mozilla Developer Network. Listę znaków i ich funkcji w wyrażeniach regularnych zawierają skoroszyt Reference w szablonach aplikacji Survey123 i dokument Wskazówki.

Obliczenia

Obliczenia są wykonywane w kolumnie calculation (obliczenia) pytania. Obliczenia często są powiązane z typem pytań calculate (obliczenie), ale mogą być także stosowane w pytaniach typu integer (liczba całkowita), decimal (liczba dziesiętna), text (tekst) i select_one (wybierz jedną). Wynik obliczenia może zostać użyty w wyrażeniu relevant (odpowiednie) lub constraint (ograniczenie) za pośrednictwem odniesienia do nazwy pola pytania typu calculate (obliczenie).

Pytanie typu calculate (obliczenie) jest ukryte i nie jest wyświetlane w formularzu. Oznacza to, że pytania typu calculate (obliczenie) mogą być używane do przechowywania wartości, które nie muszą być wyświetlane w formularzu, ale które są dołączane do warstwy obiektowej.

Można na przykład utworzyć pytanie typu calculate (obliczenie), nadać mu nazwę calc, a w jego kolumnie calculation (obliczenia) wstawić następujące wyrażenie:

${question_1} + ${question_2} + ${question_3}

Używając wyniku, ustal istotność następnego pytania:

${calc} <= 100

Obliczeń można używać z odpowiedziami w polach date. W wyniku wykonania tego obliczenia zostaje oszacowana liczba lat między wprowadzoną datą a dniem dzisiejszym (idealnie nadaje się do obliczania wieku osób):

int((today() - ${birth_date}) div (1000 * 24 * 60 * 60 * 365.25))

Czasami potrzebna jest tylko część wartości lub obcięta wersja kompletnej odpowiedzi. Operator substr zwraca tylko część ciągu znakowego zdefiniowaną przez liczby znajdujące się po tym operatorze. Pierwsza liczba wyznacza punkt początkowy zaznaczenia, a druga oznacza długość (jeśli nie ma drugiej wartości, zaznaczone zostają wszystkie znaki do końca ciągu znakowego). W tym przykładzie operator substr usuwa wszystkie znaki poza ciągiem znakowym od znaku 10 do 15:

substr(${previous_question}, 10, 15)

Gdy pierwsza liczba jest ujemna, operator substr rozpoczyna liczenie znaków od końca ciągu znakowego, a nie od początku. W tym przykładzie zwracanych jest tylko pięć ostatnich znaków odpowiedzi:

substr(${previous_question}, -5)

Do kontrolowania tego, kiedy w formularzu wykonywane są obliczenia, można używać parametru calculationMode. Więcej informacji można znaleźć w temacie Tryb obliczania.

Kolumny calculation (obliczenia) można również użyć na potrzeby funkcji agregujących w powtórzeniach. Więcej informacji zawiera temat Powtórzenia.

Podczas korzystania z obliczeń należy pamiętać o następujących najważniejszych wskazówkach:

• Podczas używania random() rozważ dodanie stałej, aby uniknąć otrzymania wyniku wynoszącego zero (0), na przykład random()+0.5. Wartość 0 może spowodować zwrócenie odpowiedzi pustej.
• Podobnie jak w przypadku ograniczeń należy upewnić się, że na początku wszystkich wartości dziesiętnych z zakresu od -1 do 1 w formule znajdują się zera (0), ponieważ symbol dziesiętny na początku powoduje błędy.
• Typ danych wyniku obliczeń zależy od typu danych każdego elementu tych obliczeń. Jeśli obliczenia są wykonywane na dwóch liczbach całkowitych, ich wynikiem jest liczba całkowita. Jeśli obliczenia zawierają znakowy typ danych, może okazać się, że operator + łączy ze sobą wartości, a nie dodaje je do siebie. Aby uniknąć nieoczekiwanych wyników, użyj funkcji number(), aby upewnić się, że wartości znakowe są traktowane w obliczeniach jako liczby. Na przykład obliczeniem dodającym pytanie question1 typu integer (liczba całkowita) do pytania question2 typu text (tekst) jest ${question1} + number(${question2}).

Wskazówka:

W specyfikacji XLSForm z pytaniem typu calculation (obliczenie) domyślnie wiązany jest typ string (ciąg znakowy). Aby zastąpić to ustawienie domyślne, należy wprowadzić wymagany typ (na przykład int lub decimal) w kolumnie bind::type odpowiadającej danemu pytaniu. Można również użyć żądanego typu pytania (na przykład integer lub decimal) i skonfigurować dla tego pytania wygląd hidden.

Uwaga:

Funkcje lub operatory matematyczne w pytaniach typu text (tekst) zwracają wynik NaN w aplikacji internetowej Survey123. Aby połączyć pytania typu text (tekst), użyj funkcji concat() zamiast operatora +.

Złożone funkcje matematyczne

W kolumnie calculation (obliczenia) można także wykonywać bardziej złożone operacje matematyczne. W tym przykładzie obliczane jest pole powierzchni, gdy dany jest promień. Używane są funkcje pi i potęgowa:

pi() * pow(${plot_radius}, 2)

Typową metodą pomiaru wysokości drzewa jest mierzenie w punkcie obserwacyjnym kąta od poziomu wzroku do wierzchołka drzewa oraz odległości od tego samego punktu obserwacyjnego do podstawy drzewa. Jeśli kąt do wierzchołka drzewa jest mierzony w stopniach, do przekształcenia go w radiany można użyć następującego przekształcenia:

${angle_to_top_degrees} * (pi() div 180)

Gdy miara kąta jest wyrażona w radianach, wysokość drzewa (zaokrągloną do dwóch miejsc po przecinku) można określić, wykonując następujące obliczenie:

round(((tan(${angle_to_top_radians}) * ${distance_to_tree}) + ${height_to_eyes}),2)

Formatowanie dat

Do formatowania wartości daty i czasu można używać w polu format-date funkcji calculation. Może to być użyteczne w celu wyświetlenia elementów dat dla użytkowników lub utrwalenia ich w postaci ciągów znakowych.

W tym przykładzie wartość zawarta w poprzednim pytaniu typu time (czas) lub typu dateTime (data i czas) jest zwracana w 24-godzinnym formacie czasu:

format-date(${previous_time},'%H:%M')

W funkcji format-date można używać następujących kwalifikatorów:

Kwalifikator	Opis
%3	Milisekundy dopełnione zerami (000–999)
%a	Trzyliterowa skrócona nazwa dnia
%b	Skrócona nazwa miesiąca
%d	Dzień miesiąca dopełniony zerami
%e	Dzień miesiąca
%h	Godzina (czas 24-godzinny)
%H	Godzina dopełniona zerami (czas 24-godzinny)
%m	Miesiąc dopełniony zerami
%M	Minuta dopełniona zerami
%n	Miesiąc w postaci liczbowej
%S	Sekunda dopełniona zerami
%W	Numer tygodnia Notatka: Kwalifikatora %W nie można używać w funkcji format-date, jeśli w pytaniu typu date (data) używane jest obliczenie. Ten kwalifikator działa w pytaniach typu date (data), w których występuje wartość domyślna.
%y	Dwucyfrowy rok
%Y	Czterocyfrowy rok

Notatka:

W pytaniach typu dateTime (data i czas) nie jest obsługiwany czas wyrażony w jednostkach mniejszych od jednej minuty. Chcąc rejestrować w datach czas w jednostkach mniejszych od jednej minuty, należy rozważyć użycie pytań typu start (początek) i end (koniec).

Wartości puste

Podczas używania ograniczeń i obliczeń odnoszących się do innych pytań, należy zastanowić się, co się stanie, jeśli dane pytanie będzie puste (to znaczy nie będzie na nie odpowiedzi). Wartości puste są reprezentowane przez:

• Wartość NaN (not a number - nie jest liczbą) dla pytań typu integer (liczba całkowita) i decimal (wartość dziesiętna). Jest to wartość specjalna reprezentująca brak prawidłowej wartości.
• Wartość '' (pusty ciąg znakowy) dla pytań typu text (tekst). Domyślnym typem danych pytań typu select_one (wybierz jedną), select_mulitple (wybierz wiele), rank (ranga) i pytań ukrytych także jest typ text (tekst). Jeśli pytania typu select_one (wybierz jedną), select_multiple (wybierz wiele) i pytania ukryte są puste lub gdy pytanie typu rank (ranga) nie zostało zmodyfikowane przez użytkownika, wówczas zawierają one pusty ciąg znakowy.

W zależności od tego, czy wartość jest liczbą, czy tekstem, obliczenia będą zachowywać się odmiennie.

W pytaniach typu integer (liczba całkowita) lub decimal (wartość dziesiętna), ma miejsce następujące zachowanie:

• Żadne wyrażenia matematyczne zawierające wartość NaN nie są wykonywane, a pytanie pozostaje puste.
• Funkcje min() i max() zostają wykonane, a wszystkie wartości NaN są ignorowane.
• Porównanie wartości NaN z dowolną inną wartością zwraca wartość prawda (true) tylko w przypadku zastosowania operatora is not equal (nie jest równe). Wszystkie inne wyrażenia zwracają wartość fałsz (false).

Pytania typu text (tekst) zachowują się w następujący sposób:

• Połączenie pytań typu text (tekst) zostaje wykonane, jeśli występują wartości puste. Na przykład wyrażenie concat("Hello" + ${firstName}, ", how are you?") zwraca wynik "Hello , how are you?", gdy pytanie firstName jest puste.
• Funkcje min() i max() zostają wykonane, a wszystkie puste ciągi znakowe są ignorowane.
• Pusta odpowiedź tekstowa jest równa innej pustej odpowiedzi tekstowej i zawsze mniejsza niż każdy niepusty tekst.

Do sprawdzania, czy pytanie jest puste, służy funkcja string-length. Funkcji string-length można używać z pytaniami wszystkich typów. Na przykład wyrażenie string-length(${Question1}) zwraca wartość 0, gdy pytanie Question1 jest puste.

Za pomocą funkcji count-selected można także sprawdzić, czy pytanie typu select_one (wybierz jedną) bądź select_multiple (wybierz wiele) jest puste. Na przykład wyrażenie count-selected(${question2}) zwraca wartość 0, jeśli nie dokonano wyboru w pytaniu question2.

Pytania typu select_multiple (wybierz wiele) i rank (ranga)

Odpowiedzi na pytania typu select_multiple (wybierz wiele) i rank (ranga) są przechowywane w inny sposób, niż odpowiedzi na pytania pozostałych typów. Wszystkie zaznaczone odpowiedzi na pytanie typu select_multiple (wybierz wiele) wprowadzone w takiej kolejności, w jakiej zostały wybrane, rozdzielone przecinkami. Na przykład wybranie odpowiedzi 'A' i 'B' (w tej kolejności) powoduje wyświetlenie odpowiedzi 'A,B'. Odpowiedzi na pytanie typu rank (ranga) są także przechowywane na liście wartości rozdzielanych przecinkami, w kolejności od najniższej do najwyższej rangi w momencie przesłania.

Niektóre z funkcji formularza XLSForm nie działają z pytaniami typu select_multiple (wybierz wiele) i rank (ranga). Jeśli na przykład w kolumnie relevant (odpowiednie) odnoszącej się do pytania select_multiple (wybierz wiele) zostaje wprowadzona odpowiedź 'A', a odpowiedzią na ankietę jest 'A,B', ta odpowiedź nie jest uważana za istotną. W tym przypadku rozwiązaniem jest użycie funkcji selected(), która określa, czy którakolwiek z tych wartości znajduje się na liście.

Użycie następującego wyrażenia w kolumnie relevant (odpowiednie) pytania powoduje wyświetlenie pytania, jeśli użytkownik wybrał wartość 'A' jako jedną z odpowiedzi na to pytanie typu select_multiple (wybierz wiele). Dodatkowe odpowiedzi w tym pytaniu select_multiple nie powodują zmiany tego zachowania.

selected(${previous_question}, 'A')

Pobieranie wartości z pliku .csv

Za pomocą funkcji pulldata() w kolumnie calculation (obliczenia) pytania można wstępnie wczytać dane z pliku .csv. Istnieją dwa sposoby dołączenia pliku .csv: ręczne umieszczenie pliku w folderze media ankiety lub połączenie do pliku .csv hostowanego w systemie ArcGIS.

Funkcja pulldata() wymaga podania czterech następujących parametrów w tej kolejności:

1. Nazwa pliku .csv zawierającego listę wartości. Nazwa nie zawiera rozszerzenia nazwy pliku .csv.
2. Nazwa kolumny w pliku .csv zawierającej wartość, która ma zostać zwrócona.
3. Nazwa pola klucza w pliku .csv, które zostanie użyte do wyszukania wartości.
4. Wartość klucza do wyszukania w polu klucza.

Te wartości można definiować bezpośrednio lub za pośrednictwem zmiennych zdefiniowanych w innym miejscu ankiety. W następującym przykładzie obliczenie zwraca adres e-mail osoby nazwanej w poprzednim pytaniu z pliku .csv o nazwie info:

pulldata('info', 'email', 'name', ${respondent_name})

Ta sama funkcja pulldata() działa także w kolumnie constraints (ograniczenia), co uniemożliwia użytkownikom wysyłanie odpowiedzi innych niż te znajdujące się w pliku .csv. W kolumnie constraints (ograniczenia) ta sama formuła powoduje, że w formularzu nie są akceptowane żadne wartości, które nie znajdują się w kolumnie name (nazwa) w pliku .csv.

Funkcja pulldata() ma pewne ograniczenia. Nazwy pola klucza dotyczą te same ograniczenia co kolumny name (nazwa) w arkuszu choices (możliwości wyboru) — te wartości nie mogą zawierać spacji ani znaków spoza zestawu ASCII. Ponieważ mamy do czynienia z plikami .csv, użycie przecinka w dowolnym z tych pól sprawia, że funkcja pulldata() zwraca nieprawidłowe wyniki.

Jeśli wartości w pliku .csv są dłuższe niż 255 znaków, należy wprowadzić większą wartość w kolumnie bind::esri:fieldLength zarówno dla pytania, które jest wypełniane przy użyciu zawartości pliku .csv, jak i dla wszystkich pytań używanych jako dane wejściowe funkcji pulldata(). Jeśli w pliku .csv znajdują się wartości większe niż maksymalna długość jednego z tych pól, nie udaje się przesłanie odpowiedzi na ankietę i zostaje wyświetlony błąd o kodzie 1000.

Notatka:

Funkcji pulldata() nie można używać do wypełniania wartości w pytaniach typu select_multiple (wybierz wiele).

Gdy używana jest funkcja pulldata(), nazwy kolumn w pliku .csv nie mogą być puste i nie mogą zawierać spacji, łączników ani innych znaków specjalnych.

Zaleca się kodowanie pliku .csv z użyciem kodowania znaków UTF-8. Jeśli do utworzenia pliku Microsoft Excel jest używany program .csv, należy zapisać ten plik jako CSV UTF-8.

Pobieranie wartości z obiektu JSON

Za pomocą funkcji pulldata("@json") można wyodrębnić poszczególne właściwości z obiektu JSON. Ta funkcja jest często używana jako uzupełnienie innych funkcji, takich jak pulldata("@javascript") i pulldata("@layer"). Składnia tej funkcji jest następująca:

pulldata("@json", <question name>, "<JSON property>")

Parametry funkcji pulldata("@json") są następujące:

• question name — nazwa pytania, które zawiera obiekt JSON, na przykład: ${json_response}.
• JSON property — właściwość, która ma zostać pobrana z obiektu JSON. Do podania położenia właściwości w strukturze JSON należy użyć okresów. Na przykład w celu pobrania właściwości City z obiektu address, użyj "address.City".

W poniższym przykładzie wynik operacji odwróconego geokodowania jest zwracany jako obiekt JSON w pytaniu typu text (tekst) o nazwie json_response:

Zwracana jest odpowiedź lokalizatora podobna do następującej:

{
    "address": {
        "Match_addr": "Eiffel Tower",
        "LongLabel": "Eiffel Tower, Paris, Île-de-France, FRA",
        "ShortLabel": "Eiffel Tower",
        "Addr_type": "POI",
        "Type": "Historical Monument",
        "PlaceName": "Eiffel Tower",
        "AddNum": "",
        "Address": "",
        "Block": "",
        "Sector": "",
        "Neighborhood": "Paris 07",
        "District": "Paris",
        "City": "Paris",
        "MetroArea": "",
        "Subregion": "Paris",
        "Region": "Île-de-France",
        "RegionAbbr": "",
        "Territory": "",
        "Postal": "",
        "PostalExt": "",
        "CntryName": "France",
        "CountryCode": "FRA"
    },
    "location": {
        "x": 2.294520000000034,
        "y": 48.85832000000005,
        "spatialReference": {
            "wkid": 4326,
            "latestWkid": 4326
        }
    }
}

Funkcja pulldata("@json") służy do pobrania właściwości City z obiektu address:

pulldata("@json", ${json_response}, "address.City")

Długość i szerokość geograficzna są pobierane z obiektu location:

pulldata("@json", ${json_response}, "location.x")

pulldata("@json", ${json_response}, "location.y")

Notatka:

Do uzyskiwania dostępu do poszczególnych właściwości obiektu nadrzędnego służy kropka. Gdy kropka wchodzi w skład właściwości, należy ją umieścić w nawiasach kwadratowych [ ]. Na przykład, aby pobrać właściwość o nazwie City.Population z obiektu address, wyrażenie musi mieć postać pulldata("@json", ${json_response}, "address.[City.Population]").

Dostęp do obiektu w tablicy obiektów można uzyskać przez podanie jego pozycji w tablicy w nawiasie kwadratowym. Indeksy tablicy JSON rozpoczynają się od zera. Poniżej znajduje się przykład obiektu JSON zwróconego przez inteligentne atrybuty. Zawiera on tablicę classes:

{
    "classNames": "person,bottle,keyboard",
    "classes": [
        {
            "name": "person",
            "score": 0.67421875,
            "xmin": 47,
            "ymin": 20,
            "xmax": 1086,
            "ymax": 262
        },
        {
            "name": "bottle",
            "score": 0.7625,
            "xmin": 237,
            "ymin": 469,
            "xmax": 552,
            "ymax": 639
        },
        {
            "name": "keyboard",
            "score": 0.55078125,
            "xmin": 28,
            "ymin": 49,
            "xmax": 1078,
            "ymax": 385
        }
    ]
}

W powyższym przykładzie następujące wyrażenie zwraca wynik 0,67421875 z pierwszego obiektu w tablicy classes:

pulldata("@json", ${results}, "classes[0].score")

Aby zwrócić liczbę obiektów w tablicy, można użyć właściwości length. W powyższym przykładzie następujące wyrażenie zwraca długość równą 3:

pulldata("@json", ${results}, "classes.length")

Zapytanie o warstwę obiektową

Do zapytania o warstwę obiektową, tabelę obiektów lub usługę mapową z obsługą zapytań można użyć funkcji pulldata("@layer"). Można wykonać zapytanie atrybutowe lub zapytanie przestrzenne. Zapytanie atrybutowe używa operacji getRecord lub getValue:

pulldata("@layer", "getRecord", "<URL>", "<WHERE clause>")
pulldata("@layer", "getValue", "<JSON property>", "<URL>", "<WHERE clause>")

Zapytanie przestrzenne używa operacji getRecordAt lub getValueAt:

pulldata("@layer", "getRecordAt", "<URL>", <location>, "<WHERE clause>")
pulldata("@layer", "getValueAt", "<JSON property>", "<URL>", <location>, "<WHERE clause>")

Operacje getRecord i getRecordAt zwracają obiekt JSON zawierający pojedynczy obiekt i wszystkie jego atrybuty. Operacje getValue i getValueAt zwracają pojedynczą wartość z obiektu zamiast całej odpowiedzi na zapytanie.

Parametry funkcji pulldata("@layer") są następujące:

Parametr	Opis
JSON property	Wymagane w przypadku operacji getValue i getValueAt. Wartość, która ma zostać pobrana z odpowiedzi na zapytanie. Przykłady: "attributes.COUNTRY" "geometry"
location	Wymagane w przypadku operacji getRecordAt i getValueAt. Lokalizacja punktu, odnośnie do którego ma zostać wysłane zapytanie do warstwy obiektowej. Musi to być pytanie typu geopoint (punkt geograficzny). Przykład: ${location}
URL	Wymagane. Adres URL warstwy obiektowej lub tabeli, do której jest wysyłane zapytanie. Ten parametr przyjmuje dodatkowe parametry żądania. Przykład: "https://services.arcgis.com/P3ePLMYs2RVChkJx/ArcGIS/rest/services/World_Countries/FeatureServer/0"
WHERE clause	Opcjonalne. Wyrażenie WHERE, które filtruje warstwę obiektową lub tabelę. Gdy brak klauzuli WHERE, jest używana wartość domyślna "1=1". Przykład: "COUNTRY='Canada'"

Wskazówka:

Funkcja pulldata("@layer") zwraca pierwszy rekord w odpowiedzi na zapytanie. Zaprojektuj i przetestuj swoje zapytanie, aby upewnić się, że uzyskiwane są pożądane wyniki. Zapytanie można doprecyzować, korzystając z klauzuli WHERE i dodatkowych parametrów żądania opisanych poniżej.

Funkcja pulldata("@layer") buforuje odpowiedzi na zapytania, aby poprawiać wydajność. Aby nie używać pamięci podręcznej i wymusić wykonywanie nowych żądań przy każdym uruchomieniu funkcji, dodaj parametr time=now do adresu URL. Przykład: concat(${layer_url}, "?t=", now()).

Poniższy przykład przedstawia zapytanie do warstwy obiektów poligonowych światowych stref czasowych i zwraca strefę czasową, w której znajduje się punkt geograficzny:

Operacja getRecordAt służy do pobrania strefy czasowej przecinanej przez punkt geograficzny za pomocą następującej składni:

pulldata("@layer", "getRecordAt", "https://services.arcgis.com/P3ePLMYs2RVChkJx/arcgis/rest/services/World_Time_Zones/FeatureServer/0", ${location})

Atrybut ZONE jest następnie wyodrębniany z odpowiedzi na zapytanie za pomocą funkcji pulldata("@json"). Inną możliwością jest użycie operacji getValueAt w obliczeniu pulldata("@layer") do pobrania bezpośrednio atrybutu ZONE bez konieczności użycia osobnego pytania do zapisania odpowiedzi na zapytanie. Zapoznaj się z następującym przykładem:

pulldata("@layer", "getValueAt", "attributes.ZONE", "https://services.arcgis.com/P3ePLMYs2RVChkJx/arcgis/rest/services/World_Time_Zones/FeatureServer/0", ${location})

Funkcji pulldata("@layer") można użyć w ograniczeniach. Na przykład można zastosować ograniczenie względem pytania typu geopoint (punkt geograficzny), aby uniemożliwić użytkownikom wprowadzenie lokalizacji spoza obszaru zainteresowania.

Operacja getRecordAt zwraca obiekt JSON dla kraju, w którym znajduje się punkt geograficzny, za pomocą następującej składni:

pulldata("@layer", "getRecordAt", "https://services.arcgis.com/P3ePLMYs2RVChkJx/ArcGIS/rest/services/World_Countries/FeatureServer/0", ${location}, "COUNTRY='Canada'")

Nazwa kraju jest wyodrębniana w pytaniu typu text (tekst) za pomocą funkcji pulldata("@json"). Ograniczenie ${country}='Canada' jest następnie stosowane względem pytania typu geopoint (punkt geograficzny), aby upewnić się, że lokalizacja mieści się w regionie Kanady.

Parametry żądania

Zapytanie pulldata("@layer") można doprecyzować za pomocą dodatkowych parametrów żądania, takich jak distance, orderByFields i resultOffset. Więcej informacji o parametrach żądania zawiera temat Zapytanie (usługa obiektowa/warstwa). Funkcja pulldata("@layer") obsługuje tylko żądania, które zwracają obiekt funkcji.

Aby uwzględnić te parametry w zapytaniu, należy dodać je do adresu URL po znaku zapytania. Parametry dodatkowe są rozdzielane znakami &. W poniższym przykładzie parametry orderByFields i resultOffset zostały dodane do adresu URL warstwy obiektowej w celu zwrócenia nazwy dziesiątego najbardziej zaludnionego powiatu w Kalifornii:

pulldata("@layer", "getValue", "attributes.NAME", "https://services5.arcgis.com/jMCHJcLe13FaKCFB/arcgis/rest/services/US_Counties/FeatureServer/1?orderByFields=POPULATION DESC&resultOffset=9", "STATE_NAME = 'California'")

Zagregowane zapytanie może posłużyć do zwrócenia statystyk warstwy obiektowej przez użycie parametru outStatistics: Przy użyciu tego parametru można obliczyć następujące statystyki: liczba, suma, minimum, maksimum, średnia, odchylenie standardowe i wariancja.

W poniższym przykładzie jest zwracana liczba powiatów w wybranym stanie:

pulldata("@layer", "getValue", "attributes.TotalCount", concat("https://services5.arcgis.com/jMCHJcLe13FaKCFB/arcgis/rest/services/US_Counties/FeatureServer/1", '?outStatistics=[{"statisticType": "count","onStatisticField": "objectId","outStatisticFieldName": "TotalCount"}]'), concat("STATE_NAME = '", ${state_name}, "'"))

W poniższym przykładzie jest zwracana suma pola POPULATION dla wszystkich powiatów w wybranym stanie:

pulldata("@layer", "getValue", "attributes.TotalPopulation", concat("https://services5.arcgis.com/jMCHJcLe13FaKCFB/arcgis/rest/services/US_Counties/FeatureServer/1", '?outStatistics=[{"statisticType": "sum","onStatisticField": "POPULATION","outStatisticFieldName": "TotalPopulation"}]'), concat("STATE_NAME = '", ${state_name}, "'"))

Notatka:

Funkcja pulldata("@layer") obsługuje wszystkie parametry żądania wymienione na liście Zapytanie (Usługa/warstwa obiektowa) poza następującym:

• f
• outFields
• outSR
• resultRecordCount
• returnCountOnly
• returnGeometry
• returnIDsOnly
• token

Pobieranie lokalizacji z listy

Można zezwolić użytkownikom na pobieranie lokalizacji z warstwy obiektowej na podstawie wyboru z listy możliwości wyboru w pytaniu typu select_one (wybierz jedną). Wybór jest wysyłany jako tekst, a odpowiadająca mu geometria jest wysyłana jako lokalizacja na potrzeby odpowiedzi na ankietę. To podejście jest równoważne pytaniu typu location list (lista lokalizacji) w kreatorze internetowym Survey123.

Aby utworzyć listę lokalizacji, dodaj pytanie typu select_one (wybierz jedną) o wyglądzie search (wyszukiwanie) lub autocomplete (autouzupełnianie). Wygląd search (wyszukiwanie) powoduje zapełnienie listy wartościami z warstwy obiektowej. Wygląd autocomplete (autouzupełnianie) powoduje wyświetlenie wartości na liście rozwijanej, co jest przydatne w przypadku bardzo długiej listy zwróconej z warstwy obiektowej.

Skonfiguruj wyrażenie search(), aby pobrać listę wartości z warstwy obiektowej: W pytaniach typu geopoint (punkt geograficzny), geoshape (kształt geograficzny) lub geotrace (ślad geograficzny) dodaj wyrażenie pulldata("@layer"), aby pobrać geometrię dla obiektu wybranego z listy.

W poniższym przykładzie respondenci wybierają wodomierz z pytania typu select_one (wybierz jedną) o nazwie meter_id. Geometria wodomierza jest pobierana z warstwy obiektowej Wodomierze i zapisywana w pytaniu typu geopoint (punkt geograficzny):

Więcej informacji na temat wyglądu search (wyszukiwanie) zawiera temat Wyszukiwanie.