XPATH es un minilenguaje que se usa para recorrer nodos (etiquetas) dentro de un documento XML. En XForms (Formulario en XML), se puede usar XPATH para acceder a nodos/preguntas específicas en la instancia.
Antes de aprender a usar XPATH con Kontrolid cabe recordar que “Formalmente un formulario en KONTROLID es un documento en formato XML que sigue un subconjunto de la especificación: W3C XForms specification. Aunque usted pudiera desarrollar formularios directamente con esta especificación, eso es algo complejo..”. De hecho aunque en ninguna parte se explica, se puede subir un archivo en XML en vez de la plantilla Excel y es aceptado.
Así entonces y como una vista general, la estructura XML de un formulario (XForms) sería como lo siguiente. Partiendo de un formulario xlsform como en este ejemplo:
Descargándolo en formato XML así:
Se ve así (Se muestra sólo algunas partes):
Lo resaltado en amarillo abajo corresponde a la pregunta dentro del ciclo de repetición:
El formato básico de una ruta XPATH es /a/b/c donde a se refiere a la instancia de mayor jerarquía del documento XML, b es hijo y así sucesivamente.
Las rutas XPATH pueden ser absolutas o relativas. Si la ruta empieza con / es absoluta. Esto significa que se empieza a buscar desde el nodo principal del documento.
Si la ruta XPATH no empieza con /, la ruta es relativa, eso significa que se empieza a buscar desde algún nodo (llamado nodo contexto o simplemente contexto) que varía según el contexto donde se esté usando el XPATH. En general, las rutas relativas empiezan con ../ y los “../ pueden repetirse tantas veces como niveles haya.
Para referenciar preguntas usando expresiones XPATH absolutas se empieza construyendo la ruta con un / desde el nodo raíz de formulario. En el caso de Kontrolid el nodo raíz es /main y se sigue con / por los distintos niveles hasta llegar a la pregunta.
Ejemplo:
/main/pregunta1 (Fila: 91 de la imagen del archivo XML arriba)
Para fórmulas en restricciones (constraints) o relevancia (relevant) , el nodo contexto es el nodo al que está haciendo referencia. Para esto hay dos clases de referencias relativas que son útiles:
- que se refiere al nodo contexto en sí mismo sea a la pregunta misma. Ej: . >= 5
- que se refiere al nodo padre del nodo contexto, por ejemplo, cuando estamos en un ciclo de repetición. Por eso usamos position(..) para hacer referencia al índice del ciclo de repetición donde se encuentra la pregunta.
Ejemplos: Con referencia al siguiente XLSForm,
En XPATH referencias absolutas es:
Fila 7: /main/pregunta1 (Fila: 91 de la imagen del archivo XML arriba)
Fila 10: /main/gruporepeticion/gruporepeticion.1 (Fila: 104 de la imagen del archivo XML arriba)
Fila 13: /main/Grupo/q5 (Fila: 111 de la imagen del archivo XML arriba)
En XPATH referencias relativas son:
Fila 7: ../pregunta1
Fila 10: ../../gruporepeticion.1
Fila 13: ../../q5
Para incluir un constraint para la pregunta1 (fila 7) y que sólo admita como texto = ‘Hoy’ se puede usar cualquiera de las tres opciones de abajo significando lo mismo:
Cuando se trabaja con grupos de repetición, se necesita tener cuidado y entender claramente el contexto.
La expresión ${gruporepeticion.1} es expandida por el convertidor a /main/gruporepeticion/gruporepeticion.1 y funcionará perfectamente cuando hace referencia al mismo contexto es decir se encuentra en el mismo ciclo donde está.
Igual podrá hacer referencia con el punto . a la pregunta misma o usar la referencia absoluta en una pregunta calculate
En cambio, una ruta relativa fallará y se quedará siempre pidiendo una respuesta correcta:
Esto ocurre porque la referencia relativa desconoce el contexto (A que ciclo?) se está refiriendo.
Si la referencia absoluta se hace por fuera del ciclo, el calculo producirá un error, porque el contexto es diferente y no se sabe a que ciclo de la pregunta se estará refiriendo
Cuando se necesita hacer referencia desde afuera a una pregunta del grupo de repetición deberá especificarse el ciclo o índice al que pertenece, ya sea mediante la función indexed-repeat(${pregunta},${gruporepeticion},índice) o en XPATH usando calificadores de posición. En este último caso se debe especificar así:
Ruta-a-grupo-repeticion/grupo-de-repeticion[position(.)=valor]/pregunta o elementos adicionales de la ruta
En el siguiente ejemplo, para acceder al segundo valor (ciclo 2) de la pregunta de repetición sería:
De hecho, esta referencia absoluta se resuelve de manera correcta aún dentro del ciclo de repetición y mostrará correctamente el valor cuando llegue al ciclo 2 y posteriores:
Para que las referencias relativas funcionen se usa una expresión current()/.. que sería el equivalente al . en preguntas sencillas.
current()/.. hace referencia al grupo donde se encuentra la pregunta
En el siguiente ejemplo, en la fila 4 se hace el cálculo del índice anterior y en la fila 6 usamos la expresión position(.), o sea la posición actual sea igual a la pregunta índiceanterior de este contexto current()/..
Nota: Es posible que al cargar y luego descargar desde el servidor el mismo formulario XLSForm que contenga predicados XPATH, éstos aparezcan distintos vs. El original. Esto se debe a incompatibilidades del convertidor de XLSForm a XML, por esa razón si va a usar XPATH siempre debe asegurar de reescribir la referencia nuevamente cada vez que reuse un formulario o le haga modificaciones con una nueva versión.
