Webbox
Webbox는 설문 내에 외부 웹 페이지를 모달 iframe으로 임베드하여 조사원이 양식을 떠나지 않고 참조 자료를 보거나 외부 도구와 상호 작용할 수 있게 합니다.
Webbox는 외부 웹 페이지를 설문 내 모달 팝업 (iframe)으로 임베드합니다. 조사원이 레이블이나 메모 텍스트의 버튼을 탭하면 페이지가 양식 내 전체 화면 오버레이에서 열리고, 닫으면 정확히 있던 위치로 돌아옵니다. 이를 통해 별도의 브라우저 탭을 열지 않고도 참조 자료, 지도, 대시보드 또는 사용자 정의 도구를 표시할 수 있습니다.
구문
label 또는 note 레이블 열에 <webbox> HTML 태그를 직접 삽입합니다:
<webbox src='https://example.com/reference' title='참조 가이드'>참조 가이드 열기</webbox>
| 속성 | 설명 |
|---|---|
src | iframe에 로드할 URL. 단일 따옴표와 큰따옴표 모두 지원합니다. |
title | 모달 헤더 바에 표시되는 텍스트. 일반 텍스트를 지원합니다. |
| (내용) | 설문 필드에 표시되는 클릭 가능한 버튼 레이블 |
기본 예시
| type | name | label |
|---|---|---|
| note | ref_guide | <webbox src='https://docs.example.com/field-guide' title='현장 가이드'>📖 현장 가이드 열기</webbox> |
이것은 “📖 현장 가이드 열기"라는 레이블이 있는 버튼을 렌더링합니다. 탭하면 현장 가이드 웹사이트를 표시하는 모달이 열립니다.
지도 임베딩
| type | name | label |
|---|---|---|
| note | area_map | <webbox src='https://maps.example.com/survey-area' title='설문 지역 지도'>🗺 지도 보기</webbox> |
임베드된 페이지에 양식 값 전달
calculation 열에서 concat()을 사용하여 URL에 양식 필드 값을 추가하고 레이블에서 결과를 참조합니다:
| type | name | label | calculation |
|---|---|---|---|
| calculate | webbox_url | concat('https://dashboard.example.com/household?id=', ${household_id}) | |
| note | hh_dash | <webbox src='${webbox_url}' title='가구 대시보드'>대시보드 열기</webbox> |
<webbox> 태그의 src 속성은 레이블이 calculate 필드에서 계산될 때 ${fieldname} 참조를 지원합니다. calculate 필드에서 전체 URL을 구성하고 참조합니다.
반복 상호 작용: 삭제 버튼
Webbox는 레이블 내에서 반복 그룹 관리를 위한 특수 액션 태그도 지원합니다:
<delete-repeat-current>이 행 제거</delete-repeat-current>
<delete-repeat-last>마지막 행 제거</delete-repeat-last>
이들은 탭 시 반복 인스턴스를 삭제하는 버튼으로 렌더링됩니다. 반복 그룹 내 (또는 바로 뒤)의 note 필드에 배치합니다:
| type | name | label |
|---|---|---|
| begin_repeat | items | 항목 |
| text | item_name | 항목 이름 |
| note | delete_btn | <delete-repeat-current>✕ 이 항목 제거</delete-repeat-current> |
| end_repeat |
임베드된 페이지와의 통신 (postMessage)
webbox iframe과 상위 양식은 브라우저의 postMessage API를 사용하여 통신할 수 있습니다. 상위는 열릴 때 iframe에 init 메시지를 보냅니다. 임베드된 페이지는 다음으로 응답할 수 있습니다:
delete-repeat-current— 현재 반복 인스턴스 삭제를 트리거합니다delete-repeat-last— 마지막 반복 인스턴스 삭제를 트리거합니다
이를 통해 사용자 정의 웹 도구 (예: 그리기 도구, 인터랙티브 지도)가 사용자가 iframe 내에서 동작을 확인할 때 양식 액션을 트리거할 수 있습니다.
모범 사례
- 참조 자료 (가이드라인, 조회 표, 지도)에 webbox를 사용합니다 — 양식 자체에 있어야 하는 데이터 수집에는 사용하지 마세요.
- 임베드된 URL이 기기의 네트워크에서 액세스 가능한지 확인합니다 — webbox는 연결이 필요합니다.
- 임베드된 페이지를 모바일 친화적으로 유지합니다 — 모달은 최대 너비 800px이고 뷰포트 높이의 80%입니다.
- 일반적인 레이블 (“여기를 클릭하세요”) 대신 설명적인 버튼 텍스트를 사용합니다 (예: “마을 지도 보기”).
- 모달을 닫으면 설문으로 돌아온다는 것을 조사원에게 알립니다 — 일부 사용자는 iframe 오버레이를 닫는 방법을 모를 수 있습니다.
제한 사항
- Webbox는 임베드된 URL을 로드하기 위해 네트워크 연결이 필요합니다.
- 일부 외부 사이트는
X-Frame-Options또는Content-Security-Policy헤더를 통해 iframe 임베딩을 차단합니다 — 이러한 사이트는 webbox에서 사용할 수 없습니다. - 조사원이 질문에서 이동할 때 모달이 닫힙니다 — iframe의 저장되지 않은 상태는 손실됩니다.
- Webbox는 rtSurvey 웹 양식 확장으로 다른 ODK 호환 클라이언트에서 작동하지 않을 수 있습니다.