Funciones JavaScript en formularios de encuesta

Puede utilizar la función pulldata() para invocar funciones JavaScript, lo que le permite utilizar técnicas avanzadas y lógica más allá de lo que es posible a través de XLSForm solamente.

Puede administrar y editar las funciones JavaScript en la pestaña Scripts de Survey123 Connect. En esta pestaña, puede crear un archivo JavaScript, revisar el código y probar la función. Esta pestaña no sustituye totalmente a un entorno de desarrollo integrado (IDE, por sus siglas en inglés), que puede proporcionar validación de código y análisis de prácticas recomendadas para ayudar a desarrollar funciones JavaScript, pero la pestaña se ha diseñado para ayudar con la integración de estas funciones en Survey123.

Herramientas de script en Survey123 Connect

Las siguientes herramientas están disponibles en el menú de la pestaña Scripts de Survey123 Connect:

  • Archivos de script: muestra todos los archivos JavaScript ubicados en la carpeta Scripts de su encuesta. Seleccione el archivo que desee ver y editar.
  • Abrir carpeta de scripts: abra el explorador de archivos en la ubicación de la carpeta Scripts de una encuesta.
  • Nuevo archivo de scripts: cree un archivo de script en la carpeta Scripts de una encuesta. Escriba el nombre de archivo y haga clic en Crear.
  • Seleccionar función: resalta la primera función del archivo abierto y presenta los parámetros para la prueba.
  • Guardar: guarda los cambios del archivo abierto.
  • Iniciar editor externo: inicia el IDE JavaScript predeterminado del sistema con el archivo abierto.

Haga clic en la herramienta Seleccionar función para probar el comportamiento de la primera función en el archivo escribiendo valores para cada parámetro y visualizando el resultado. Una vez que haya terminado la función, puede copiar la instrucción pulldata que se presenta aquí y pegarla en XLSForm. Si tiene sesión iniciada en su organización, haga clic con el botón derecho en cualquiera de los parámetros y haga clic en Pegar token, si es necesario.

Nota:
Los errores de sintaxis básicos se muestran en la pestaña Scripts con un indicador de error junto con el número de línea. El manejo de errores se debe implementar dentro de la función JavaScript. La salida de la consola se muestra en la pestaña Scripts, de modo que, al incluir mensajes de consola en su función, puede ver errores, advertencias y mensajes de información junto con la salida.

Sintaxis básica

Puede invocar funciones JavaScript personalizadas para devolver valores. Utilice la siguiente sintaxis para invocar funciones JavaScript personalizadas con la función pulldata():

pulldata("@javascript", "yourJSFile.js", "yourFunction", "parameter1", "parameter2")

Debe almacenar sus archivos personalizados de JavaScript en una carpeta llamada scripts en el directorio de la encuesta. En el ejemplo anterior, la función JavaScript espera dos parámetros, pero puede agregar cualquier cantidad de parámetros de función.

La función pulldata() también puede extraer valores específicos de un objeto JSON producido por una función JavaScript. El siguiente ejemplo extrae el campo attributes.ZIP_CODE de la función JavaScript ejecutada en la pregunta json_output:

pulldata("@json", ${json_output}, "attributes.ZIP_CODE")

Sugerencia:

Para consultas espaciales y de atributos en las capas de entidades de ArcGIS, considere utilizar la función pulldata("@layer") en lugar de pulldata("@javascript"). La sintaxis pulldata("@layer") está diseñada específicamente para consultas de capas de entidades y se admite en encuestas públicas. Para obtener más información, consulte Consultar una capa de entidades.

Repeticiones

Puede pasar todos los valores de una repetición a funciones JavaScript. La función pulldata("@javascript") admite dos estilos de implementación para recuperar los valores de una repetición. El que se debe utilizar depende de si desea que la función JavaScript interactúe con un campo o con muchos campos de una repetición.

Si una pregunta de una repetición se transfiere como un parámetro de función, la función JavaScript recibe un conjunto de valores de la pregunta especificada de la siguiente manera:

pulldata("@javascript", "yourJSFile.js", "yourFunction", ${question1})

Si se pasa un nombre de repetición como un parámetro de función, la función JavaScript recibe el parámetro como un conjunto de filas de todos los valores de la repetición de la siguiente manera:

pulldata("@javascript", "yourJSFile.js", "yourFunction", ${repeat1}, "question1")

Cada uno de ellos produce un objeto JSON con preguntas individuales como propiedades en ese objeto.

Nota:

La aplicación web Survey123 no permite acceder a valores de repeticiones con pulldata("@javascript"). Puede recopilar valores para una pregunta única de una repetición en la aplicación web utilizando join() para convertir la lista de valores en una cadena separada por caracteres y, a continuación, dividir los valores en la función JavaScript.

A partir de la versión 3.14 de Survey123, los valores vacíos que se transfieren a través de una función JavaScript ahora pueden devolver undefined o null. Por ello, debe escribir funciones JavaScript para tener en cuenta la posibilidad de un valor undefined.

Otras propiedades

A veces, especialmente cuando se utiliza JavaScript para acceder a servicios web y servicios seguros de ArcGIS, es posible que necesite propiedades que no están disponibles a través de XLSForm estándar. Survey123 incluye las propiedades que se enumeran a continuación, que se pueden extraer utilizando la siguiente estructura:

pulldata("@property", "propertyname")

  • portalurl
  • token
  • online: un valor booleano que indica si el dispositivo tiene conectividad de red.
  • language: el idioma que se utiliza actualmente en la encuesta.
  • locale: el Objeto regional utilizado en la encuesta actual. Esta propiedad solo es útil para las funciones JavaScript.
  • localeinfo: el objeto de AppStudio LocaleInfo utilizado en la encuesta actual que contiene el código de idioma en varias notaciones. Esta propiedad solo es útil para las funciones JavaScript.
  • timezone: el código de zona horaria.
  • utcoffset: la diferencia, en horas, respecto de la hora universal coordinada (UTC) para la zona horaria local.
Puede utilizar estas propiedades con la función pulldata("@javascript"). El siguiente ejemplo utiliza la propiedad de token para generar un token para un servicio de entidades:

pulldata("@javascript", "myJSFunctions.js", "returnFirstIntersectingFeature", "https://services.arcgis.com/P3ePLMYs2RVChkJx/arcgis/rest/services/USA_ZIP_Codes_2016/FeatureServer/0", string(${location}), "*", pulldata("@property", "token"), true)

Limitaciones conocidas

Estas son las limitaciones conocidas a la hora de utilizar funciones JavaScript en los formularios de encuesta:

  • El modelo de objetos del documento objeto (DOM) no es compatible.
  • Los marcos de trabajo como JQuery, Ember y Angular no son compatibles.
  • No puede acceder a los archivos locales.
  • Las llamadas asíncronas no son compatibles.
  • Las funciones JavaScript solo son compatibles en los formularios completados por usuarios de la misma organización que el autor del formulario.
  • Las funciones JavaScript no son compatibles con encuestas públicas.
  • Una función pulldata("@javascript") no se puede invocar dentro de una función pulldata("@json") en la aplicación web Survey123.