Contenido
Sintaxis en Restricción,relevancia y cálculos
| Operador | Uso | Ejemplo | Notas |
|---|---|---|---|
| Hacer referencia a la propia respuesta | . | . < 5 | En una constraint, El punto (.) se refiere al valor capturado en la pregunta. En este caso el valor debe ser menor a 5. |
| Negación | not(expression) | not(selected(${pregunta}, ‘c’)) | La pregunta es relevant en la medida que ‘c’ no haya sido seleccionada en la pregunta: pregunta |
| Y | and | selected(., ‘c’) and selected(., ‘d’) | En una constraint, tanto ‘c’ y ‘d’ necesitan haber sido seleccionadas en la pregunta actual |
| Ó | or | selected(., ‘c’) or selected(., ‘d’) | En una constraint, cualquiera de las dos ‘c’ o ‘d’ necesitan haber sido seleccionadas en la pregunta actual |
| Mayor que | > | . > 10.51 | En una constraint, la pregunta actual debe ser mayor que 10.51. Se puede combinar con igual (=) para hacer “mayor o igual que” >= |
| Menor que | < | . < 10.51 | En una constraint, la pregunta actual debe ser menor que 10.51. Se puede combinar con igual (=) para hacer “menor o igual que” <= |
| Diferente | != | .!=25 | Es relevante solo cuando el valor sea diferente de 25 |
| Respuesta seleccionada | selected((${pregunta}, value) | relevant=”selected(${pregunta}, ‘n’)” | Es relevante si la respuesta ha sido seleccionada en la pregunta de selección multiple. |
| Contar número respuestas seleccionadas | count-selected(${multiple_choice_q}) | count-selected( . ) < 4 El número de opciones seleccionadas en la pregunta de selección multiple debe ser menor que 4. | |
| Valor (n+1)-esimo Seleccionado | selected-at(${multiple_choice_q}), n) | selected-at(multi-select, 3) | Al usarlo con position(..) en un grupo de repetición debe restarse uno.position(..) – 1 |
| Expresión Regular | regex(value, expression) | constraint=”regex(., ‘[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+\.[A-Za-z]{2,4}’)” [A-Za-z0-9._%+-]+ Indica cualquier caracter mayuscula, minúscula, digitos y ._%+- son permitidos. Por ejemplo $#& y otros no son permitidos @ debe ir \. representa el punto porque el punto sólo representa cualquier caracter. {2,4} indica mínimo 2 y máx 4 regex(.,[A-Z]+) regex(.,[A-Z0-9]+) | En este ejemplo se valida los caracteres permitidos en un correo electrónico. Ver definición en Wikipedia. Aqui se valida cualquier número de caracteres pero sólo admite MAYUSCULAS y números. Correcto: 893AZ2 BGH333 FFGHHJ Incorrecto: 45gh75 |
| Igual | = | . = number(’10’)” | En una restricción, respuesta actual debe ser igual a 10. En este ejemplo se usa la función number para convertir texto a número antes de hacer la evaluación. |
| Condicional (if) | if(condition, a, b) Si la condición es verdadera ( true) aplica “a” De lo contratrio usa “b” | if(${count} < 10, ${count}, 10) | Si la cuenta es menor que 10 entonces use el valor, de lo contrario use 10. Este ejemplo usa el valor de repetición de un bloque begin repeat para definir un máximo |
| Largo del texto | string-length(question) | string-length(.) < 5 | En una constraint, la longitud de caracteres ingresados debe ser menos de 5 |
| Convierte a Booleano | boolean(* arg) | boolean(5) = true | Un número es true si y solo si es positive, negativo o cero. Un string es true si su longitud es mayor que cero. |
| Verdadero | true() | true | Devuelve valor true |
| Falso | False() | false | Devuelve Valor false |
| Convierte String a Boolean | Boolean-from-string(* arg) | Boolean-from-string(1) = true | Retorna valor true si el argumento es ‘true’ o 1 |
Funciones de Fecha
| Operador | Uso | Ejemplo |
|---|---|---|
| Formatear fecha como texto | format-date(${pregunta}, formato) format-date-time(${pregunta}, formato) La lista de formatos de fecha está especificada en la siguiente sección. | format-date(${dob}, ‘%Y %n %d’) “2011 2 26” format-date-time(${dob}, ‘%Y-%n-%d %H:%M’) “2011-2-26 12:28” |
| Convertir una fecha/hora a número decimal | decimal-date-time(${pregunta}) Corresponde al valor en días y fracción del tiempo desde el 1 enero de 1970 (Tiempo UNIX). 1 año tiene 365.24 días La fracción de día considera el Tiempo Universal Coordinado 0. Util como parte de un cálculo de fecha. Por cada día adicional agregue 1 al número. Por cada hora adicional agregue 1/24 al número. No esta disponible en Form. Web. decimal-date No existe | decimal-date-time( . ) > (decimal-date-time(${dob}) + 10.0416666) La fecha ingresada debe ser mayor que 10 días y una hora después de la fecha de nacimiento. decimal-date-time(today()) Así 18241.75 corresponde al día 11 de Diciembre de 2019 a la 1 PM. La fracción 0.75 * 24 hrs = 18 hrs – 5 (Hora Colombia) = 1 PM. |
| Convertir una hora a número decimal | decimal-time(${pregunta}) A diferencia de decimal-date-time, la fracción de día considera el Tiempo Universal Coordinado Local. Por lo tanto no requiere corrección. Util como parte de un cálculo de fecha. Por cada hora adicional agregue 1/24 al número. No esta disponible en Form. Web. | decimal-time( . ) > decimal-time(${time_of_birth}) + 10 div 24 La hora ingresada debe ser mayor que 1 hora después de la hora de nacimiento. decimal-time(now()) Es 0.5465 correspondiente a la 1 PM Colombia. |
| Convertir un decimal a una fecha | date-time(${pregunta}) Convierte una fecha calculada a un format fecha. | date-time(decimal-date-time(${dob})+10) La fecha es igual a la fecha de nacimiento más diez días. date-time(0) = 1969/12/31 que corresponde al día 0 |
| Fecha actual | today() | |
| fecha y hora actual | now() | |
| Convertir texto a fecha | date(${pregunta}) o date(‘2021-02-05’) donde las comillas sencillas (”) indican texto | constraint=. >= date(‘2011-11-12’) |
Ejemplo de uso funciones de fecha:
La siguiente tabla muestra los resultados para un ingreso de:
fecha (date): q1, q4 es decimal-date-time(${q1})
fecha-hora (datetime): q2, q5 es decimal-date-time(${q2}) y hora (time): q3, , q6 es decimal-date-time(${q2})
El registro se tomó el 1 de enero de 2017 a las 12 de la noche. q1 se registra como 2017-01-01 y q4 es 17167.20833333. Corresponde al día 17167 que va desde el día cero en 31 Dic 1969. El 1 de enero 2018 sería 17167 + 365 = 17532.
q2 considera la hora estándar UTC. Como Colombia es UTC-5 se le debe sumar 5/24 = 0.208333 por eso q5 = 17167.0.208333.
q3 que sólo captura tiempo, toma la hora local. Por eso q6 = 0
Formato de Fechas
- %Y : Año 4 digitos
- %y : Año 2 digitos
- %m : mes numérico con 0 adelante para menos de 10
- %n : mes numérico
- %b : mes en texto corto (Toma el idioma especificado en el celular Español: ene. feb. mar. abr. may. jun. jul. ago. sep. oct. nov. dic)
- %d : día del mes con 0 adelante para menos de 10 (01, 02, 03….10, 11)
- %e : día del mes sin 0 adelante para menos de 10 (1, 2, 3, 4, 4, 6, 7, 8, 9, 10 , 11 ..)
- %H : hora, format 24 horas con 0 adelante para menos de 10 (01, 02, 03….10, 11)
- %h : hora, formato 24 (1, 2, 3, 4, 4, 6, 7, 8, 9, 10 , 11 ..)
- %M : minuto con 0 adelante para menos de 10
- %S : segundos con 0 adelante para menos de 10
- %3 : milisegundos con 0 adelante para menos de 10
- %a : día en texto corto. Toma el idioma seleccionado en móvil ( Español: lun. mar. mie. jue. vie. sáb. dom.)
En el dispositivo, en ajustes -> Fecha y Hora puede verificar la referencia exacta de día y mes para los puntos 5 y 13 referidos arriba.
Funciones de Texto
| Función | Uso | Ejemplo |
|---|---|---|
| Concatenar Texto | concat(texto1, texto2, texto3…) concat(${pregunta_de_repeticion}) | concat(${nombre}, ${direccion}, ${ciudad}) Reúne en un solo texto el nombre, dirección y ciudad. Se usa en una pregunta tipo “calculate” o para definir el nombre de una instancia en la pestaña settiings de un archive XLSForm. Concatena todos los valores de la pregunta en el grupo de repetición. Es equivalente a como se usa sum o max. |
| Concatenar Texto con separador | join(separador, texto1, texto2, texto3…) Igual que concatenar except que agrega un caracter de separación (separador) entre cada item que se está juntando. join(separador,${pregunta_de_repeticion}) | join(‘;’,’Detalles’,${nombre}, ${edad}) Si el valor del nombre fuera “John Smith” y el valor de la edad fuera “26” el valor devuelto por esta función es: Detalles;John Smith;26 Esta función es muy útil para la definición de datos o etiquetas en gráficos (chart) ya que éstos deben separarse con ‘:’, ‘::’ o ‘==’ según corresponda: join(‘==’, ${labels2}, ${data2}) join(‘:’, ‘1.1’,’2.5′,’3.8′, ‘10.4’) Concatena todos los valores de la pregunta en el grupo de repetición con un separador entre cada uno. |
| Extraer una cadena | substr(string, inicia, [termina]). Retorna una subcadena empezando en el índice inicia (empieza en cero) hasta el índice termina. Termina es opcional Ej: Para obtener el primer character inicia empieza en 0 y termina en 1 y así sucesivamente. | substr(‘Test’,1,2)=’e’ |
| Extraer una cadena antes de una subcadena | substring-before(string, subcadena_objetivo). Retorna la subcadena antes de la primera coincidencia con la subcadena_objetivo | substring-before (‘Olimpico’,’mpi’) = ‘Oli’ |
| Extraer una cadena después de una subcadena | substring-after(string, subcadena_objetivo). Retorna la subcadena depués de la primera coincidencia con la subcadena_objetivo | substring-after (‘Olimpico’,’mpi’) = ‘co’ |
| CopiarYReemplazar | translate(string, CaracterIni, CaracterFin). Retorna una copia de la cadena (string) donde cada carácter en CaracterIn es reemplazado por CaracterFin Definición XPATH oficial | translate(‘kontrolid’,’abcdefghijklmnopqrstuvwxyz’,’ABCDEFGHIJKLMNOPQRSTUVWXYZ’) =’KONTROLID’ Este ejemplo muestra de una manera práctica cómo puede convertirse una cadena en minúscula a su correspondiente mayúscula. |
| Normalizar espacios | normalize-space(string) Elimina todos los espacios innecesarios en una cadena | normalize-space(‘Esto es una prueba ‘) = ‘Esto es una prueba’ |
| Contiene | contains(string1, string2). Devuelve true si el string1 contiene el string2 | contains(‘caracol’, ‘raco’)=true |
| Prefijo | starts-with(string1, string2). Devuelve true si el string1 empieza con el string2 | starts-with(‘caracol’, ‘cara’)=true |
| Sufijo | ends-with(string1, string2). Devuelve true si el string1 termina con el string2 | ends-with(‘caracol¿, ‘col’)=true |
| Convierte a número | number(${num-plots}) | |
| Convierte a entero | int(${num-plots}) | |
| Convierte a texto | string(${num-plots}) | |
| Obtener la etiqueta de una opción en una pregunta seleccionada (selección única) | jr:choice-name(${pregunta}, ‘${pregunta}’). | jr:choice-name(${tipo_de_transporte}, ‘${tipo_de_transporte}’) Note que el Segundo parámetro lleva comillas simples (´). |
| Largo del texto | string-length(question) | string-length(‘Hola’)=4 |
Funciones Matemáticas
La tabla a continuación contiene tanto operadores y funciones matemáticas generales como funciones que le pueden ayudar a hacer referencia a los datos dentro de las repeticiones, es decir, llamados a subformularios, ya que facilitan identificar a qué iteración del subformulario se está refiriendo.
| Operador | Uso | Ejemplo |
|---|---|---|
| Más | + | ${a} + ${b} |
| Menos | – | ${a} – ${b} |
| Multiplicación | * | ${a} * ${b} |
| División | div | ${a} div ${b} |
| Módulo | mod | 3 mod 2 = 1 |
| Potencia | pow(a,b) | pow(${ancho}, 3) Devuelve ${ancho} * ${ancho} * ${ancho} |
| Número Aleatorio | random() Devuelve un número aleatorio entre 0.0 (inclusive) y 1.0 (exclusivo) | round((random() * ${numero_hijos} + 0.5), 0) Genera un número aleatorio entre 1 y el número de hijos en un hogar. El uso sería por ejemplo encuestar acerca de un hijo con preguntas adicionales. Se puede combinar con la función position(..) para mostrar el hijo que ha sido seleccionado. |
| Redondear | round(a,b) Redondea el número “a” al número de decimales “b” | round(${peso_kg}, 2) round(0.5, 0) = 1 |
| Suma de un grupo de repetición | sum((${pregunta_de_repeticion}) La pregunta debe ser cuantitativa | sum(${peso}) |
| Máximo en un grupo de repetición | max((${pregunta_de_repeticion}) La pregunta debe ser cuantitativa | Valor máximo en un grupo de repetición |
| Mínimo en un grupo de repetición | min((${pregunta_de_repeticion}) La pregunta debe ser cuantitativa | Valor mínimo en un grupo de repetición |
| Cuenta de una pregunta de repetición | count(${pregunta_de_repeticion’) La pregunta debe ser cuantitativa | Cuenta todos los elementos de un grupo de repeticion |
| Cuenta de una pregunta de repetición los elementos sin vacíos | count-non-empty(${pregunta_de_repeticion’) La pregunta debe ser cuantitativa | Cuenta todos los elementos de un grupo de repetición excluyendo los que no tienen valor |
| Otras funciones matemáticas | Log, log10,sin, cos, tan, asin, acos, atan, atan2, sqrt, exp, exp10, pi() como está especificado en: https://www.w3.org/TR/xpath-functions-30/#func-math-atan2 | Sin(${radianes}) |
| Checklits – Al menos X de, Mínimo X | checklist(numero min, numero max, string v1, v2..vn) Chequea que el numero de respuestas de un conjunto de variables si/no está entre mín y máx inclusive. Min y max pueden ser -1 para indicar que no aplica. | Se puede usar para validar que un determinado número de respuestas opcionales se han contestado, por ejemplo mínimo 3 respuestas contestadas |
| Checklist con peso – Al menos X de, Mínimo X | weighted-checklist(min, max, v1, w1, v2, w2, v3, w3, …, vn, wn) | Igual que la función anterior solo que se establece unos “pesos” asociados a cada variable de acuerdo a su importancia. |
Funciones para acceder grupos de repetición (Repeat) también conocido como Subformularios
| Función | Uso | Ejemplo |
|---|---|---|
| Referenciar una pregunta dentro de un grupo de repetición | indexed-repeat(${pregunta_de_repeticion}, ${grupo_de_repeticion}, indice) Indice empieza en 1 | indexed-repeat(${nombre}, ${geopolygon_a}, 2) Devuelve el valor para la pregunta nombre en la segunda ocurrencia del grupo de repetición geopolygon_a. |
| Indice del grupo de repetición actual | position(..) Tome nota de los 2 puntos seguidos | indexed-repeat(${nombre}, ${nombres}, position(..)) Devuelve el nombre del grupo de repetición nombres en el mismo índice que el grupo de repetición actual. |
| Obteniendo el número de repeticiones realizadas | count() | count(${grupo_de_repeticion}) Devuelve el número de repeticiones |
Funciones Online
| Función | Uso | Ejemplo |
|---|---|---|
| lookup | Esta función se puede usar en lugar de pulldata en los cálculos. Toma los mismos parámetros que pulldata. Sin embargo, el archivo csv no se descarga. Esto puede ser útil cuando tiene archivos de referencia muy grandes. | lookup(’hhdatos’,’miembros’,’hhid_key’,${hhid}) No disponible en formularios web |
| lookup_choices | Esta función se puede usar en lugar de la función search() y usa los mismos parámetros. Sin embargo, el archivo csv no se descarga. Esto puede ser útil cuando tiene archivos de referencia muy grandes. | Lookup_choices(‘hijos’, ‘in’, ‘clase_v’, ‘clase1’) No disponible en formularios web |
| lookup_image_labels | lookup_image_labels (imagen) | Se puede utilizar para llamar al servicio AWS Rekognition para identificar objetos en una imagen. Úselo en un cálculo. La imagen debe ser un archivo jpg. lookup_image_labels ($ {a_picture}) No disponible en formularios web Antes de usarla confirme con su agente comercial si tiene este servicio disponible |
| get_media | Descarga un archivo multimedia de un servidor. Este archivo multimedia se puede usar como valor predeterminado para una pregunta de imagen, video o audio. | Úselo en un cálculo para establecer una imagen como valor inicial para una pregunta. Utilice una selección para identificar una imagen base para descargar y luego anotar. Para conocer más a fondo la función get_media() consulte el artículo Uso de Imágenes del servidor o Internet |
Otras Funciones
| Función | Uso | Ejemplo |
|---|---|---|
| search | search(nombre_archivo_csv) Devuelve etiquetas de selección de un archivo .csv | Recupera las etiquetas de selección para una pregunta select o select_one desde un archive CSV. Para usar esta función se necesita también establecer algunos valores en la columna appearance para que el Sistema reconozca que columnas se usan del archive como valor de selección y etiqueta. Para más detalle busque el tutorial correspondiente en ayuda No está disponible en Form. Webs |
| search para valores que corresponden | search(nombre_archivo_csv, opción de correspondencia, columna_a_buscar, valor-a_buscar) 4 opciones de correspondencia: ‘contains’ (contiene), ‘startswith’, (empieza con), ‘endswith’ (termina con) y ‘matches’ (correspondencia exacta) Devuelve etiquetas de selección de un archivo csv que correspondan a los valores suministrados | search(‘hijos’, ‘matches’, ‘clase_v’, ‘clase1’) Busca en el archive hijos.csv. Devuelve todas las filas donde el valor de la columna ‘clase_v’ es ‘clase1’. |
| search con filtro | search(nombre_archivo_csv, opción de correspondencia, columna_a_buscar, valor_a_buscar, columna de filtro , valor de filtro) Una variación de la búsqueda básica. Esto agrega un filtro extra. | search(‘hijos’, ‘matches’, ‘clase_v’, ‘clase1’, ‘inscritos_v’, ‘si’) Devuelve las filas como en el ejemplo anterior sin embargo solo donde el valor “inscritos_v” es ‘si’. No disponible para Form. Web |
| search con criterio ‘in’ o ‘not in’ en selección múltiple | search(nombre_archivo_csv,’in’, columna_a_buscar, pregunta de selección múltiple o lista) | search(‘hijos’, ‘in’, ‘clase_v’, ‘clase1’) Busca en el archive hijos.csv. Devuelve todas las filas donde el valor de la columna ‘clase_v’ esté en el subconjunto ‘clase1’. Aquí clase1 es una pregunta de selección múltiple o lista. La funcionalidad está prevista para proveer un método que permita visualizar únicamente las opciones antes seleccionadas por una selección múltiple. |
| pulldata | pulldata(nombre_archivo_csv, columna de datos, columna de llave única, valor de llave única) La cabecera de columna de llave única debe terminar con los caracteres _key | pulldata(’hhdatos’,’miembros’,’hhid_key’,${hhid}) Recupera un valor de la columna miembros en el archivo hhdatos.csv donde la columna hhid_key tiene el valor correspondiente a la pregunta hhid. Esta función es equivalente a la función de excel Buscarv”. |
| coalesce | coalesce(valor, valor) | coalesce(${edad}, 0) Coalesce devuelve un valor establecido en caso de que no encuentre un valor. Esta función es útil en caso de funciones matemáticas donde puedan surgir errores por falta de valor. En este ejemplo la edad se fija en 0 si la variable está vacía. |
| once | once(${edad}) | Permite establecer valores predeterminados dinámicos para los que desea obtener un valor inicial, pero luego el usuario debe establecer el valor. El valor solo se evaluará una vez mientras el formulario esté abierto. |
| default | default(${pregunta}) | El valor se evaluará cada vez que cambie la pregunta de origen. Por ejemplo en default(${edad}), si cambia la respuesta a la pregunta ${edad} el valor se recalculará. Sin embargo, el valor no se recalculará al guardar el formulario. |
| uuid | Uuid() | Genera un identificador aleatorio único que cumple con el estándar: RFC 4122 version 4 |
| Digest Función resúmen o hash | digest(datos, algoritmo, método de codificación (optional)) | Calcula y devuelve el valor hash de la cadena de datos usando la cadena del algoritmo hash indicado, y codifica este valor hash usando método de codificación opcional. Las opciones para el algoritmos son: MD5, SHA-1, SHA-256, SHA-384, SHA-512. Si no se especifica el tercer parámetro el método de codificación será base64. Opciones válidas son base64 y hex. Esta función puede ser útil si, por ejemplo, se quiere construir un identificador único de datos sensibles como la cédula sin comprometer estos datos. Aqui hay una explicación interesante de los algoritmos hash Esto es útil si no desea almacenar información confidencial en el servidor. El valor hash de los datos se puede utilizar como un sustituto no identificativo alternativo del valor introducido. Puede usar la apariencia phoneonly en la pregunta sensible para que no se almacene en el servidor. |
| base64-decode(texto codificado) | base64-decode(${texto}) | Decodifica todos los bytes de la entrada utilizando el esquema de codificación Base64, asumiendo que los bytes codificados representan caracteres UTF-8. Devuelve una cadena de caracteres UTF-8. |
| extract-signed(texto firmado y codificado, llave publica) | extract-signed(${texto}, ${llave}) | Dado un texto firmado y codificado en base64, y una llave pública como entradas, verifica que los primeros 64 bytes sean una firma Ed25519 válida. Si la firma es válida, devuelve la parte del mensaje (sin firma) del contenido como una cadena UTF-8. Si la firma no es válida, devuelve vacio. |
| area | area(${geoshape}) o area(${ubicacion1},${ubicacion2},${ubicacion3},…) | Devuelve el área en metros cuadrados. Donde de una pregunta de tipo geoforma o un conjunto de nodos de preguntas de geopuntos. |
| distancia distance | distance(${pregunta}) o distance(${pregunta1},${pregunta2},${pregunta3},…) | Devuelve la distancia en metros de un conjunto de puntos geográficos, o una línea o el perímetro de una forma. distance(${punto1},${punto2}) devolverá la distancia en metros del punto1 al punto2 |
