guía completa · ES

Construyendo un cuestionario
desde cero, celda por celda.

XLSForm es el estándar que convierte una planilla común en un formulario digital completo — con lógica de salto, validación, GPS, fotos y varios idiomas — listo para correr en ODK Collect, KoboToolbox o Enketo. Esta guía construye una encuesta de hogares paso a paso y documenta todos los tipos de pregunta y configuraciones, con ejemplos que puede copiar y convertir con rxform.

1 · Anatomía de un XLSForm

Un XLSForm es un archivo .xlsx (o .xls/.ods) con hasta tres hojas principales:

• survey — las preguntas, en su orden de aparición. Columnas mínimas: type, name y label.
• choices — las listas de opciones de las preguntas de selección. Columnas mínimas: list_name, name y label.
• settings — título, identificador, versión, idioma por defecto y demás configuración del formulario (una sola fila de datos).

Reglas de oro para la columna name (preguntas, grupos y opciones):

2 · El primer formulario

El formulario útil más pequeño tiene tres filas en la hoja survey:

La pregunta de la fila 4 usa la lista si_no, definida en la hoja choices:

Y la hoja settings da identidad al formulario:

Convierta y listo:

$ rxform encuesta_hogares.xlsx
encuesta_hogares.xml

3 · Todos los tipos de pregunta

Texto y números

• text — texto libre. Para cajas más altas, parameters = rows=5.
• integer / decimal — números, con teclado numérico en el dispositivo.
• range — control deslizante; límites vía parameters = start=0 end=10 step=1. Con appearance = rating se vuelve estrellas.

Fechas y horas

Apariencias útiles para date: month-year, year y no-calendar.

Opciones y listas

• select_one LISTA — una respuesta. appearance: minimal (menú desplegable), likert, quick (avanza solo), columns…
• select_multiple LISTA — varias respuestas; se guardan separadas por espacios, por eso los name de las opciones no pueden contener espacios.
• rank LISTA — la persona ordena las opciones.
• select_one LISTA or_other — agrega la opción “Other” y una pregunta automática “Specify other.”.

Se permiten columnas extra en la hoja choices, que se vuelven datos de la opción — la base de los filtros en cascada:

Selecciones en cascada (choice_filter)

En el filtro, las columnas de la lista aparecen por su nombre (depto) y las respuestas previas como ${depto}. Para barajar opciones: parameters = randomize=true (con seed=42 para un orden reproducible).

Ubicación

geopoint captura un punto (precisión objetivo en metros vía parameters); geotrace, una línea; geoshape, un polígono cerrado.

Medios y archivos

image con appearance = signature se vuelve campo de firma; draw, dibujo libre. max-pixels reduce el tamaño de las fotos en el dispositivo.

Notas y confirmaciones

• note — texto mostrado, sin respuesta. Acepta ${referencias}: “¡Gracias, ${encuestador}!”. Es el único tipo que puede omitir name (rxform genera uno).
• acknowledge — exige un “ok” explícito de quien responde.

Campos invisibles

calculate computa un valor con XPath (funciones como if(), concat(), selected(), count(), round()…); hidden guarda un valor rellenable por default o integraciones.

Metadatos — recogidos solos

• start/end — marcas de tiempo de apertura/cierre; today — la fecha; deviceid, username, phonenumber, email — identificación del dispositivo/cuenta.
• audit — bitácora de auditoría del llenado; con parameters = location-priority=balanced location-min-interval=60 location-max-age=120 registra además la ubicación durante la entrevista.
• start-geopoint — captura silenciosa de la ubicación al abrir; background-audio graba el audio de la entrevista; background-geopoint captura la ubicación cuando se responde la pregunta del trigger.

4 · Lógica del formulario

Toda la lógica usa ${nombre} para referenciar respuestas anteriores.

relevant — saltar preguntas

La pregunta solo aparece cuando la expresión es verdadera. Combine condiciones con and/or; para selección múltiple use selected(${servicios}, 'agua').

constraint — validar respuestas

El punto . es la propia respuesta. El mensaje aparece cuando la regla falla.

required, default, read_only

• required = yes (o una expresión) impide avanzar sin respuesta.
• default acepta un valor fijo (42) o una expresión dinámica (today(), ${depto}) evaluada al abrir el formulario — incluso ${last-saved#sector} para heredar el último envío.
• read_only = yes muestra sin permitir edición.

trigger — recalcular cuando algo cambia

Con trigger, el campo se (re)define cada vez que cambia la pregunta referenciada — aquí, limpiando ninos cuando se edita tamano_hogar. Si hay calculation, corre en ese momento (en vez de continuamente).

5 · Grupos, repeticiones y loops

Grupos

• appearance = field-list muestra todo el grupo en una sola pantalla.
• table-list — para una secuencia de select_one con la misma lista, muestra una matriz (filas × columnas).
• El relevant del grupo aplica a todo su contenido.

Repeticiones

El bloque se repite una vez por residente. Sin repeat_count, el encuestador agrega repeticiones a mano; con una expresión (o un número), la cantidad es automática. Dentro de la repetición, use position(..) para el índice actual e indexed-repeat() para leer valores de otra repetición.

Loops sobre una lista

Genera un bloque por opción de la lista servicios, sustituyendo %(label)s y %(name)s — una pregunta “¿Cómo evalúa el servicio de Agua?”, otra “…de Alcantarillado?”, etcétera.

6 · Varios idiomas

Basta sufijar las columnas traducibles con ::Idioma (código): funciona para label, hint, guidance_hint, constraint_message, required_message, image, audio y video — en las hojas survey y choices. Defina el idioma inicial en settings → default_language = Español (es). La aplicación gana un menú de idiomas.

Medios por pregunta: las columnas image/audio/video asocian archivos (p. ej. tarjeta_respuesta.jpg) enviados junto con el formulario.

7 · Apariencias (appearance)

8 · Parámetros (parameters)

La columna parameters recibe pares clave=valor separados por espacios:

9 · La hoja settings

10 · Datos externos y entities

Listas grandes en archivo

El CSV necesita columnas name y label (o indique otras con parameters = value=codigo label=descripcion); GeoJSON usa id/title y habilita appearance = map. El archivo se sube al servidor junto con el formulario.

Consultas con pulldata()

Busca en metas.csv la columna meta de la fila donde sector = la respuesta. También existen ${last-saved#campo} (valor del último envío guardado) y la hoja entities, que permite al formulario crear y actualizar registros compartidos entre formularios (p. ej. registrar hogares en una visita y reencontrarlos en la siguiente) — con save_to en las preguntas y create_if/update_if/label en la hoja.

11 · Errores comunes — y cómo avisa rxform

• Tipo mal escrito → [sheet 'survey', row 3, column 'type'] unknown question type 'integr' — did you mean 'integer'?
• Referencia rota → '${edda}' does not match… — did you mean 'edad'?
• Lista inexistente → señala la fila y sugiere la lista más parecida.
• Grupo sin cerrar → señala la fila del begin_group y pide el end_group.
• Nombres duplicados entre hermanos, nombre con espacio/acento, pregunta visible sin label, opciones repetidas en la lista — todo con hoja, fila, columna y causa probable.

12 · Convertir y publicar

# convertir
$ rxform encuesta_hogares.xlsx
encuesta_hogares.xml

# revisar errores de autoría es solo ejecutarlo — el mensaje señala la celda
$ rxform encuesta_hogares.xlsx --stdout > /dev/null

1. KoboToolbox: suba el propio .xlsx (Kobo convierte en el servidor con pyxform — rxform genera exactamente el mismo XML, así que sirve como validación local instantánea) o despliegue el XML vía API.
2. ODK Central: publique el .xlsx o el .xml generado; adjunte los CSV/GeoJSON de listas externas.
3. Enketo: los formularios publicados reciben enlace web automáticamente.

guía · rxform — volver al inicio · referencia oficial xlsform.org