Dynamic Search (còn gọi là Search API) cho phép trường select_one, select_multiple, hoặc text tải lựa chọn từ dịch vụ web từ xa lúc chạy khi người điều tra gõ. Đây là cách tiếp cận đúng khi danh sách lựa chọn quá lớn để đóng gói trong tệp CSV, được cập nhật thường xuyên, hoặc đến từ cơ sở dữ liệu trực tiếp.

Appearance search-api()

Tìm kiếm động được cấu hình qua cột appearance bằng hàm search-api():

  search-api(method, url, post_body, value_column, display, data_path, save_path)

Tham số

Tham sốMô tả
methodLuôn dùng 'POST'
urlEndpoint API để truy vấn
post_bodyBody JSON gửi đến API. Dùng %__input__% làm placeholder cho văn bản tìm kiếm hiện tại của người điều tra
value_columnKhóa trong đối tượng phản hồi để dùng làm giá trị được lưu
displayKhóa (hoặc mẫu) để dùng làm nhãn hiển thị trong danh sách thả xuống. Hỗ trợ placeholder ##key## và biểu thức @{func}
data_pathJSONPath đến mảng đối tượng kết quả trong phản hồi (ví dụ: $.data, $.hits.hits.*._source)
save_pathTên để lưu phản hồi thô để các trường khác dùng

Ví dụ cơ bản

Tra cứu cơ sở y tế nơi người điều tra gõ một phần tên cơ sở:

typenamelabelappearance
select_onefacilityChọn cơ sở y tếsearch-api('POST', 'https://api.example.com/facilities/search', '{"query": "%__input__%"}', 'id', 'name', '$.results', 'facility_data')

API nhận {"query": "nair"} khi người điều tra gõ “nair” và trả về:

  {
  "results": [
    {"id": "HF001", "name": "Nairobi Central Clinic"},
    {"id": "HF002", "name": "Nairobi West Hospital"}
  ]
}

Danh sách thả xuống hiển thị Nairobi Central Clinic và Nairobi West Hospital; giá trị được lưu là HF001 hoặc HF002.

Định dạng hiển thị nâng cao

Dùng mẫu ##key##

Hiển thị nhiều trường trong nhãn:

  search-api('POST', 'https://api.example.com/search', '{"q": "%__input__%"}', 'id', '##name## (##district##)', '$.data', 'res')

Hiển thị như: Nairobi Central Clinic (Nairobi).

Dùng biểu thức @{func}

Áp dụng logic có điều kiện trong nhãn hiển thị:

  search-api('POST', 'https://api.example.com/search', '{"q": "%__input__%"}', 'id',
  '@{if_else(eq("##status##", "active"), "✓ ##name##", "✗ ##name##")}',
  '$.data', 'res')

Kết quả hoạt động hiển thị ✓ Tên cơ sở; không hoạt động hiển thị ✗ Tên cơ sở.

Đặt giá trị mặc định: search-default-api()

Dùng search-default-api() sau search-api() để điền sẵn trường với lựa chọn mặc định được tải từ một lần gọi API riêng (ví dụ: khi chỉnh sửa bản ghi có sẵn):

  appearance: search-api(...) search-default-api('POST', 'https://api.example.com/get', '{"id": "##saved_id##"}', 'id', 'name', '$.item')

Ký tự phân cách tùy chỉnh cho select_multiple: search-default-separator()

Với trường select_multiple, chỉ định cách ghép nhiều giá trị đã chọn trong chuỗi được lưu:

  appearance: search-api(...) search-default-separator(' || ')

Ký tự phân cách mặc định là dấu cách.

Các loại câu hỏi được hỗ trợ

Loại câu hỏiTrường hợp sử dụng
select_oneChọn một từ kết quả tìm kiếm
select_multipleChọn nhiều từ kết quả tìm kiếm
textTự động hoàn thành — người điều tra gõ tự do nhưng có thể chọn gợi ý

Dùng dữ liệu phản hồi đã lưu

save_path lưu đối tượng phản hồi API đầy đủ dưới tên đã cho. Các trường khác có thể tham chiếu bằng pulldata():

typenamelabelcalculation
select_onefacilityChọn cơ sởsearch-api(..., 'facility_data')
calculatefacility_districtpulldata('facility_data', 'district')
calculatefacility_typepulldata('facility_data', 'type')

Thực hành tốt

  1. Đảm bảo endpoint API phản hồi trong 1–2 giây — API chậm làm cho tìm kiếm có cảm giác không phản hồi.
  2. Dùng %__input__% trong post_body để API chỉ trả về kết quả khớp, không phải toàn bộ tập dữ liệu.
  3. Lập chỉ mục trường tìm kiếm phía server (ví dụ: Elasticsearch, full-text index cơ sở dữ liệu) để phản hồi nhanh.
  4. Giới hạn kết quả ở 20–50 mục mỗi truy vấn — trả về hàng nghìn kết quả làm mất ý nghĩa của tìm kiếm.
  5. Thêm yêu cầu độ dài input tối thiểu trong API để tránh kích hoạt truy vấn rộng khi nhập một ký tự.

Giới hạn

  • Dynamic Search yêu cầu kết nối mạng — không hoạt động ngoại tuyến.
  • Placeholder %__input__% được đưa vào nguyên văn; hãy làm sạch input phía server để ngăn tấn công injection.
  • Các biểu thức hiển thị @{func} phức tạp có thể được hỗ trợ hạn chế trên các phiên bản client rtSurvey.
Trang này có hữu ích không?