Dynamic question type
Dynamiczny typ pytania pozwala na określenie widgetu i zachowania walidacji pola w czasie wykonywania na podstawie odpowiedzi API lub obliczonej wartości.
Funkcja Dynamiczny typ pytania pozwala na określenie widgetu wejściowego pola i zachowania walidacji w czasie wykonywania zamiast w czasie projektowania formularza. Jest to zaawansowane rozszerzenie rtSurvey używane wtedy, gdy typ danych do zebrania zależy od konfiguracji po stronie serwera, odpowiedzi API lub wartości poprzedniego pola.
Typowym przypadkiem użycia jest konfigurowalny formularz inspekcji, w którym serwer definiuje, które pola są wymagane, jaki mają typ (tekst, integer, select itp.) oraz jakie opcje są dostępne — bez konieczności przebudowywania formularza dla każdej konfiguracji.
Jak to działa
Pole oznaczone jako dynamiczny typ pytania używa callapi() do pobrania konfiguracji z API. Odpowiedź API definiuje:
- Typ widgetu wejściowego do renderowania (text, integer, select_one itp.)
- Dostępne opcje (dla typów select)
- Reguły walidacji
Pole jest wewnętrznie oznaczone jako specialFeature: isDynamicQuestionType, co informuje silnik formularza o konieczności użycia odpowiedzi API do zbudowania widgetu zamiast statycznej definicji formularza.
Konfiguracja
Krok 1: Pobierz konfigurację pola
Użyj pola calculate z callapi(), aby pobrać dynamiczną konfigurację:
| type | name | label | appearance | calculation |
|---|---|---|---|---|
| calculate | field_config | callapi | callapi('POST', 'https://api.example.com/field-config', 1, 2, 0, '$.config', 10000, 0, '', '', '{"form_id": "##form_id##", "field_id": "inspection_result"}') |
Krok 2: Odwołaj się do konfiguracji w polu dynamicznym
Pole dynamiczne używa callapi-verify() w appearance lub constraint, aby powiązać się z pobraną konfiguracją:
| type | name | label | appearance |
|---|---|---|---|
| text | inspection_result | Wynik inspekcji | callapi-verify(dynamicParams) |
Silnik formularza odczytuje field_config i dynamicznie określa, czy renderować inspection_result jako pole text, integer czy select_one.
Format odpowiedzi API
API powinno zwracać obiekt JSON opisujący konfigurację pola. Typowa odpowiedź:
{
"config": {
"type": "select_one",
"choices": [
{"value": "pass", "label": "Zaliczone"},
{"value": "fail", "label": "Niezaliczone"},
{"value": "na", "label": "Nie dotyczy"}
],
"required": true,
"constraint": ". != ''"
}
}
Przykład: Konfigurowalny formularz inspekcji
Formularz inspekcji, w którym pozycje listy kontrolnej i typy odpowiedzi są pobierane z serwera na podstawie kategorii inspekcji:
| type | name | label | appearance | calculation |
|---|---|---|---|---|
| select_one inspection_type | insp_type | Rodzaj inspekcji | ||
| calculate | checklist_config | callapi | callapi('POST', 'https://api.example.com/checklist', 1, 2, 0, '$.items', 10000, 0, '', '', '{"type": "##insp_type##"}') | |
| text | item_1 | Pozycja 1 | callapi-verify(dynamicParams) | |
| text | item_2 | Pozycja 2 | callapi-verify(dynamicParams) | |
| text | item_3 | Pozycja 3 | callapi-verify(dynamicParams) |
Serwer zwraca odpowiedni typ widgetu, etykietę, opcje i walidację dla każdej pozycji na podstawie insp_type.
Najlepsze praktyki
- Używaj dynamicznych typów pytań tylko wtedy, gdy struktura pola naprawdę zmienia się w czasie wykonywania — w przypadku statycznych formularzy używaj standardowych typów pytań.
- Upewnij się, że API konfiguracji odpowiada szybko (poniżej 2 sekund) i jest dostępne w sieci terenowej.
- Zawsze definiuj sensowny fallback w formularzu na wypadek nieosiągalności API — proste pole
textz notatką jest lepsze niż uszkodzony widget. - Wersjonuj schemat odpowiedzi API — zmiany formatu odpowiedzi wpłyną na wszystkie aktywne formularze korzystające z tego punktu końcowego.
- Przed wdrożeniem przetestuj każdą kombinację typów pól, które API może zwrócić.
Ograniczenia
- Dynamiczne typy pytań wymagają połączenia sieciowego do pobrania konfiguracji.
- Pełen zakres typów widgetów dostępnych dynamicznie zależy od wersji klienta rtSurvey — testuj na docelowej wersji.
- Jest to zaawansowane rozszerzenie rtSurvey bez odpowiednika w standardowej specyfikacji XLSForm.
- Błędy debugowania są trudniejsze do wyśledzenia, ponieważ definicja pola częściowo znajduje się w formularzu, a częściowo w odpowiedzi API.