> ## Knowledge Base Index > Fetch the complete knowledge base index at: https://docs.flokzu.com/sitemap.xml > Use this file to discover available pages before exploring further. > Pure-Markdown content can be obtained by appending a '.md' suffix to the content URLs listed in the sitemap (without the trailing slash). # Desarrollo de Scripts en Flokzu ### Introducción Muchas veces es necesario dotar de cierta inteligencia a los formularios, tanto para realizar cálculos complejos, como para realizar validaciones, detección de errores, definir lógica condicional para ocultar/mostrar campos, entre muchas otras posibilidades. Para ello, Flokzu cuenta con un *Script Engine* que provee varias funciones predefinidas a nivel de formulario para poder realizar todo tipo de validaciones, detección de errores y algoritmos. Los scripts deben ser definidos utilizando **JavaScript** como lenguaje de programación y puede aprovecharse la mayoría de las características que el lenguaje ofrece. Las funciones y atajos definidos en esta guía son una ayuda para agilizar el desarrollo de algoritmos y funciones de lógica condicional. | ✨ Si no estás familiarizado con el desarrollo en JavaScript, puedes utilizar el [Asistente IA](https://docs.flokzu.com/es/article/desarrollo-de-scripts-con-el-asistente-ia-kgwzfo/) para crear scripts en tu formulario. Simplemente describe el comportamiento deseado y el asistente creará el código por ti. # Metodología de desarrollo En Flokzu, toda la lógica debe definirse **dentro de funciones** JavaScript, las cuales serán invocadas mediante *listeners* que las asocian a eventos específicos del formulario (como el cambio de valor de un campo o la apertura de una tarea). Estos \*listeners \*se describen en detalle más adelante en este artículo. La única excepción a esta regla son los campos de tipo **autocalculado**, donde el código puede escribirse como una expresión directa sin necesidad de declarar una función ni registrar un *listener*, ya que Flokzu infiere automáticamente los campos a escuchar. Las funciones definidas pueden utilizar operaciones internas para manejar la visibilidad, errores y lectura/escritura de campos. Además podrás utilizar librerías externas como [date-fns](https://date-fns.org/) y [Sweet Alert](https://sweetalert.js.org/docs/). Todas las variables utilizadas dentro de las funciones deben ser declaradas explícitamente usando la palabra reservada `var`. Flokzu **no admite variables globales** (declaradas fuera de una función) ni la declaración implícita de variables (es decir, asignar un valor a un identificador sin haberlo declarado previamente). ###### Nombres de los campos utilizados en scripts || Para hacer referencia a un campo en las funciones predefinidas siempre debe escribirse el nombre del mismo entre [[ y ]] respetando mayúsculas, minúsculas, espacios y caracteres especiales. Ejemplo: [[Nombre Completo]] El uso de caracteres especiales como `{ } [ ] : < > = + ^ # $ / ! % * ? & |` al comienzo de los nombres de campos puede generar conflictos con scripts personalizados, especialmente porque los nombres pueden ser usados como identificadores en el DOM, y los caracteres como claves en objetos JavaScript, en selectores CSS/JS o en expresiones regulares. Muchos de estos caracteres tienen significados reservados en estos contextos, lo que puede provocar errores de sintaxis o comportamientos inesperados. Para evitar problemas, se recomienda evitar el uso de dichos caracteres en general, especialmente al inicio del nombre. # Funciones disponibles ### "Listeners" Estas funciones permiten "escuchar" cuando un campo cambia (o incluso cuando una columna de una tabla cambia) para en ese momento ejecutar una función que realice cierta lógica. Ejemplo: escuchar cuando el campo "Pasaporte" cambia su valor para verificar que el número sea válido. ###### "Escuchar" un campo Cuando el campo escuchado cambie su valor, ejecuta la función. ```javascript Flokzu.onChange( [[campo]] , NombreFuncion ); ``` ###### "Escuchar" una columna de un campo tabla Cuando una celda de la columna del campo tabla mencionado cambie su valor, se ejecutará la función. Se debe escribir entre [[ y ]] el nombre del campo luego :: y luego el nombre de la columna. ```javascript Flokzu.onTableChange( [[campo::columna]], NombreFuncion ); ``` ###### Acciones Estas funciones se ejecutarán cuando el usuario presione uno de los botones que tiene disponibles para completar la tarea. La función a su vez puede definirse de tal manera de poder identificar cual botón fue presionado (ver ejemplos al final de este post). ```javascript Flokzu.onAction( NombreFuncion ); ``` ###### Inicialización Estas funciones se ejecutarán cuando el usuario abra la instancia de proceso. Sirven para definir que sucederá en el momento cero, es decir, antes de modificar ningún campo. Esto aplica tanto a cuando se está iniciando un proceso de cero, como para cuando un usuario abre una tarea en su bandeja. ```javascript Flokzu.onInit( NombreFuncion); ``` || **Listeners en campos autocalculados:** Los "listeners" no deben incluirse cuando el script se coloca dentro de un campo de tipo autocalculado "script" ya que allí si se infieren los campos a "escuchar" a diferencia de lo que sucede con los Scripts de tarea. ### Visibilidad Estas funciones te permiten controlar cuando un campo es editable, solo lectura u oculto de forma dinámica. Para poder modificar por script la visibilidad de un campo, el mismo debe estar **editable a nivel de proceso**. Esto es, en la tarea donde se define el script, el campo debe estar marcado como Editable en la pestaña de visibilidad. ###### Ocultar un campo ```javascript Flokzu.setHidden( [[campo]] ); ``` ###### Hacer que un campo sea solo lectura ```javascript Flokzu.setReadOnly( [[campo]] ); ``` ###### Hacer que un campo sea editable (no requerido) ```javascript Flokzu.setEditable( [[campo]] ); ``` ###### Hacer que un campo sea requerido ```javascript Flokzu.setRequired( [[campo]] ); ``` ### Lectura/Escritura de campos Para poder modificar el valor de un campo usando setFieldValue el mismo debe estar al menos editable a nivel de proceso. ###### Modificar el valor de un campo (reemplaza el valor actual) Esta función es válida para todos los tipos de campo **salvo** los tipos: "Titulo / Encabezado", "Tabla", "Archivo Adjunto", "Autocalculado", "Firma" y "Checklist" que no están soportados por el momento. ```javascript Flokzu.setFieldValue( [[campo]] , valor ); ``` ###### Obtener el valor de un campo Esta función es válida para todos los tipos de campo **salvo** los tipos: "Titulo / Encabezado", "Tabla" y "firma" que no están soportados por el momento. ```javascript Flokzu.getFieldValue( [[campo]] ); ``` Casos especiales de acuerdo al tipo de campo: * Si/No: retorna un boolean (true/false). * Número Entero: retorna un número entero o NaN si el valor del campo no es un número. * Número Decimal: retorna un número con 2 decimales o NaN si el valor del campo no es un número. * Autocalculado: retorna un número con 2 decimales si el valor del campo es un número, número sin decimales si es entero, o el valor del campo en formato String en caso contrario. * Adjunto: retorna el nombre del archivo adjunto o vacío si no hay archivo seleccionado. * Combo Multiselección: opciones seleccionadas separadas por "," o vacío si no hay opciones seleccionadas. ###### Obtener todos los valores de una columna de un campo tabla Para iterar los valores, ver ejemplos al final de este post. ```javascript Flokzu.getAllColumnValues( [[campo::columna]] ); ``` ### Manejo de errores || IMPORTANTE: El manejo de errores solo puede realizarse dentro de las funciones invocadas desde "onAction". Si se lanza un error desde una función que no se ejecuta "onAction" el mismo no tendrá el efecto deseado. ||| Al lanzar un error dentro de "onAction" se impide que la tarea se complete. El usuario no podrá avanzar en el proceso hasta tanto no modifique los valores de los campos de forma tal que en el "onAction" la función no lance el error. ###### Lanzar un error para un campo El mensaje debe describir que sucedió para que el usuario pueda corregir el error. ```javascript Flokzu.error( [[campo]] , "mensaje" ); ``` ### Otros/Utiles ###### Obtener información de la instancia Devuelve los datos de la información de la instancia: referencia, nombre del proceso, descripción, tarea actual, fecha de creación, fecha de asignación, iniciador, tags, fecha de finalización. ```javascript Flokzu.currentInstance() ``` ###### Obtener el usuario actual (email) El correo del usuario que está logueado en el sistema ```javascript Flokzu.currentUser(); ``` ###### Obtener los usuarios asignados Retorna nombre y correo de los usuarios o el rol asignado a la tarea ```javascript Flokzu.getCurrentAssignees(); ``` ###### Obtener Fecha actual Retorna la fecha actual, de acuerdo a la zona horaria de la cuenta, y el formato de fecha definido ```javascript Flokzu.getCurrentDate(); ``` ###### Obtener Hora actual Retorna la hora actual, de acuerdo a la zona horaria de la cuenta, y en formato HH:mm:ss ```javascript Flokzu.getCurrentTime(); ``` ###### Obtener Fecha y Hora actual Retorna la fecha y hora actual, de acuerdo a la zona horaria de la cuenta, y el formato de fecha definido ```javascript Flokzu.getCurrentDateTime(); ``` ###### Ejecutar función de columna Es posible, mediante nuestra API, ejecutar las funciones y scripts definidos en las columnas de una tabla. Esto es útil por ejemplo si quisiéramos definir valores por defecto a una tabla. ```javascript Flokzu.executeTableFunction([[campo::columna]]); ``` ###### Obtener el ID de un campo a partir de su nombre Esta función es útil en caso de no querer/poder utilizar la notación para hacer referencia a campos [[ ]] ya sea por conveniencia, o porque el campo no se va a resolver de forma estática a nivel de script, sino que se resolverá en tiempo de ejecución dependiendo de otras variables. ```javascript Flokzu.getFieldByName( "NombreDeCampo" ); ``` ###### Modificar el tamaño de las columnas En caso de querer modificar el tamaño de las columnas de la tabla, se debe utilizar el siguiente script La suma de todos los valores deber ser = 100 en el siguiente caso nuestra tabla cuenta con 5 columnas, por ello tenemos 5 tamaños. ```javascript function resize(){ Flokzu.resizeTable( [[Nombre de Tabla]] , [ 60, 10, 10, 10, 10 ] ); } Flokzu.onInit(resize); ``` Este script debe ser ubicado en la pestaña scripts de Configurar de visibilidad y scripts | En caso de querer que el tamaño se mantenga en todas las tareas ubicarlo en -Master script- # Librerías adicionales ### date-fns Flokzu incluye [date-fns](https://date-fns.org/docs/Getting-Started) para la gestión de fechas y horas, por lo que **no es necesario importar la biblioteca** en tus scripts personalizados. La versión incluida es la 4.1.0 y se puede utilizar íntegramente en los scripts de los formularios para cualquier tarea relacionada con el cálculo de fechas. Todas las funciones de `date-fns` están disponibles a través del objeto `dateFns`, por lo que **no es necesario añadir una** instrucción `import` a tus scripts. El objeto `dateFns` ya está disponible de forma global en la aplicación. ```javascript var my_day = dateFns.parse(“12-07-2027”, “MM-dd-yyyy”, new Date()); // Crea un objeto Date var full_date = dateFns.format(my_day, “PPPP”); // 'Martes, 7 de diciembre de 2027 a las 12:00:00 a. m.' ``` || `date-fns` utiliza una API basada en funciones, en lugar de métodos de los objetos `Date`. Por lo tanto, las operaciones con fechas deben realizarse utilizando funciones de `dateFns`. **Correcto:** ```javascript dateFns.format(date, “yyyy-MM-dd”); dateFns.addDays(date, 1); dateFns.isBefore(date1, date2); ``` **Incorrecto:** ```javascript date.format(“yyyy-MM-dd”); date.addDays(1); date1.isBefore(date2); ``` | Nota: `date-fns` utiliza su propia sintaxis para el formato de fechas. Por ejemplo, para dar formato a una fecha como 2026-08-27, utiliza yyyy-MM-dd, en lugar de YYYY-MM-DD. [Más información.](https://date-fns.org/v4.1.0/docs/format) Flokzu también incluye de forma predeterminada el módulo `date-fns/locale`, que se utiliza para dar formato a las fechas utilizando los nombres de los meses, los días de la semana, etc., en diferentes idiomas (en lugar del inglés predeterminado). Se utiliza pasando un objeto de configuración regional como opción a funciones como `format`, `formatDistance`, `formatRelative`, etc. ```javascript var date = dateFns.parse('14/07/2027', 'd/MM/yyyy', new Date() ); console.log( dateFns.format(date, 'PPPP', { locale: dateFns.locale.fr }) ); // 'mercredi 14 juillet 2027' ``` ``` 🇪🇸 → dateFns.locale.es 🇫🇷 → dateFns.locale.fr 🇧🇷 → dateFns.locale.pt 🇩🇪 → dateFns.locale.de 🇬🇧 → dateFns.locale.en ``` ###### Ejemplos de uso: ```javascript // Formato con los nombres de los meses y los días de la semana en alemán dateFns.format(new Date(2027, 9, 3), 'PPPP', {locale: dateFns.locale.de}); // "Sonntag, 3. Oktober 2027" // Distancia relativa ("hace 3 días", etc.) dateFns.formatDistance(new Date(2027, 8, 7), new Date(2026, 4, 14), {locale: dateFns.locale.pt}); // "mais de 1 ano" // Formato relativo ("hoy a las..."», "ayer a las...") dateFns.formatRelative(new Date(2027, 7, 25), new Date(2027, 7, 28), {locale: dateFns.locale.es}); // "el miércoles pasado a las 00:00" ``` || Nota sobre los tokens de formato: Al utilizar `format`, los tokens como `EEEE` (nombre completo del día de la semana), `MMMM` (nombre completo del mes) y `PPPP` (fecha larga localizada) son los que realmente se benefician de la configuración regional, ya que cambian el idioma del texto. Los tokens numéricos como `HH:mm:ss` no se ven afectados por la configuración regional, ya que son solo números, no texto traducible. ### Sweet Alert Flokzu incorpora la librería [SweetAlert](https://sweetalert.js.org/docs/) para desplegar popups visualmente atractivos. La versión incluída es la 1.1.3 y puede utilizarse para indicar errores a los usuarios en el momento que cambia un campo, sin esperar a que ejecute el `onAction`. Cabe aclarar que mostrar un error con SweetAlert no impedirá que la tarea se complete. Ejemplo: ```javascript swal( {type : 'error' , title : 'Error!' , text: 'Mensaje de error'} ); ``` ### mask / inputMask Con esta librería podrás aplicar máscaras de entrada en tus campos (teléfonos, documentos, códigos, etc.). [Documentación](https://robinherbots.github.io/Inputmask/#/documentation) ||| Esta librería aplica únicamente a campos de tipo Texto. Si el campo que se pasa por parámetro es de otro tipo, simplemente se ignora el procedimiento. Algunos ejemplos que puedes implementar: ```javascript // Atar una mascara directamente a un campo Flokzu.addMask([[Telefono]], { mask: '9999-9999', placeholder: '*' }); // Esta es una máscara personalizada Flokzu.addMask([[Email]], { alias: 'email' }); // En este caso aplica un alias, una máscara definida por Inputmask Flokzu.addMask([[Campo]], { alias: 'ip' }); // Remover una mascara de un campo Flokzu.removeMask([[Campo]]); // Alias y definiciones que se pueden usar en máscaras personalizadas Inputmask.extendDefinitions({ 'K': { validator: '[0-9Kk]', casing: 'upper' } }); Inputmask.extendAliases({ flokzuRut: { mask: '9{7,8}-K', greedy: false } }); Flokzu.addMask([[Rut]], { alias: 'flokzuRut' }); ``` --- # Ejemplos * Scripts de Visibilidad * Ejecutar lógica "onAction" * Iterar los valores de una columna de campo tabla * Validar una dirección Ethereum y lanzar un SweetAlert * Restar dos campos de tipo "Fecha" con un campo Autocalculado * Restar dos campos de tipo "Hora" con un campo Autocalculado * Validar si el valor de un campo "Fecha" es menor a la fecha actual * Acotar la cantidad de decimales de un número en un script ||| **TIP:** Si una operación aritmética no está funcionando de manera deseable, es conveniente "parsear" los valores involucrados usando las funciones **parseInt** y **parseFloat** de JavaScript para asegurarse que el cálculo se realizará sobre números bien definidos. Además es deseable limitar la cantidad de decimales con la función **toFixed** (ver ejemplo más abajo). ### Scripts de Visibilidad Ver el Post [Configurar la visibilidad por script](https://docs.flokzu.com/es/article/como-configurar-la-visibilidad-por-script-17uap8/) para entender como se configuran los scripts que permiten alterar la visibilidad de un campo, así como ver distintos ejemplos. ### Ejecutar lógica "onAction" Usando onAction se puede definir lógica que va a ser ejecutada cuando se presione alguno de los botones para completar tarea. Como mencionamos anteriormente, es posible además determinar qué botón fue presionado para realizar distintas operaciones dependiendo de esto. Para poder evaluar el botón presionado, la función debe recibir dos parámetros. El primero no es de importancia para este ejemplo, mientras que el segundo si es el nombre del botón presionado. En el siguiente ejemplo, si el botón es "Rechazar" haremos requerido el campo "Motivo de Rechazo" y de lo contrario lo ocultaremos. ```javascript function validarAcciones(msg,boton){ if(boton== "Rechazar"){ Flokzu.setRequired( [[Motivo de Rechazo]] ); } else{ Flokzu.setHidden( [[Motivo de Rechazo]] ); } } Flokzu.onAction(validarAcciones); ``` ### Iterar los valores de una columna de campo tabla En algunos casos es necesario iterar sobre los valores de una columna de un campo tabla para averiguar si determinado valor ha sido ingresado y definir lógica a partir de ello. La función Flokzu.getAllColumnValues(); retorna un identificador que luego debe ser utilizado con la función "each" de jQuery para iterar los elementos. Dentro de la función "each" se utiliza `$(this).attr('value')` para obtener el valor de la celda iterada. ```javascript function iterarTabla(msg, data){ $( Flokzu.getAllColumnValues( [[campo::columna]] ) ).each( function(){ //Lanza un alert con el valor. alert( $(this).attr('value') ); } ); } Flokzu.onTableChange( [[campo::columna]] , iterarTabla ); ``` ### Validar una dirección Ethereum y lanzar un SweetAlert En este ejemplo validaremos la dirección ethereum ingresada en un campo en el momento que el usuario la ingrese, y en caso de error mostraremos un popup SweetAlert. Para ello utilizaremos la validación de un patrón con regex JavaScript para validar la dirección ethereum, luego un SweetAlert en caso de error y en caso de que además la función se ejecute al intentar completar una tarea `(sender == evt_ruteo)` entonces utilizaremos `Flokzu.error` para evitar que la misma se complete. Notar que en este ejemplo usamos una sola función tanto para `onChange` como `onAction`, e internamente distinguimos si se trata de una acción `(sender == evt\_ruteo)` o simplemente un `onChange`. ```javascript function ethValidator(sender , button){ if( ! (/^0x[a-fA-F0-9]{40}$/.test( Flokzu.getFieldValue([[Campo dirección eth]])) )){ swal({type : 'error' , title : 'Error!' , text: 'invalid address'}); if(sender == 'evt_ruteo'){ Flokzu.error( [[Campo dirección eth]] , "Dirección ETH inválida" ); } } } Flokzu.onChange( [[Campo dirección eth]], ethValidator); Flokzu.onAction(ethValidator); ``` ### Restar dos campos de tipo "Fecha" con un campo Autocalculado Con Flokzu crear un campo autocalculado que en todo momento muestre la diferencia (en días) entre 2 campos tipo "Fecha" es muy simple. Para ello utilizaremos la librería date-fns que Flokzu ya tiene incorporada. **Paso 1** Agregar 2 campos de tipo Hora (Ejemplo: "Fecha 1" y "Fecha 2"). **Paso 2** Agregar un campo autocalculado (Ejemplo: "Resta") **Paso 3** Agregar el script al autocalculado *Script considerando solo lunes a viernes* ```javascript function calcDiff() { var start = dateFns.parse(Flokzu.getFieldValue([[Fecha 1]]), 'yyyy/MM/dd', new Date()); var end = dateFns.parse(Flokzu.getFieldValue([[Fecha 2]]), 'yyyy/MM/dd', new Date()); var weekdayCounter = 0; while (start <= end) { if (!dateFns.isWeekend(start)) { weekdayCounter++; } start = dateFns.addDays(start, 1); } return weekdayCounter; } ``` *Script considerando días de corrido* ```javascript function calcDiff() { var start = dateFns.parse(Flokzu.getFieldValue([[Fecha 1]]), 'yyyy/MM/dd', new Date()); var end = dateFns.parse(Flokzu.getFieldValue([[Fecha 2]]), 'yyyy/MM/dd', new Date()); return dateFns.differenceInDays(end, start) + 1; } ``` ### Restar dos campos de tipo "Hora" **Paso 1** Agregar 2 campos de tipo Hora (Ejemplo: "Hora 1" y "Hora 2"). **Paso 2** Agregar un campo texto (Ejemplo: "Resta") **Paso 3** Agregar el script a la tarea donde se calculará la resta ```javascript function calcDiff() { // Obtener valores de los campos "Hora 1" y "Hora 2" var t1 = Flokzu.getFieldValue([[Hora 1]]; var t2 = Flokzu.getFieldValue([[Hora 2]]; const baseDate = new Date(2000, 0, 1); // Fecha de referencia arbitraria, el mismo día para ambos // Construir los objetos Date a partir de t1 y t2 var start = dateFns.parse(t1, 'HH:mm:ss', baseDate); var end = dateFns.parse(t2, 'HH:mm:ss', baseDate); var diffInSeconds = Math.abs(dateFns.differenceInSeconds(end, start)); // Calcula a diferencia de las fechas en segundos // Utiliza la fecha base para construir un objeto Date y representarlo en formato Hora var result = dateFns.format( dateFns.addSeconds(baseDate, diffInSeconds), 'HH:mm:ss'); // Actualizar el campo de resultado con la diferencia calculada Flokzu.setFieldValue([[Resta]], result); } // Llamar la función cuando el valor de los campos cambie Flokzu.onChange([[Hora 1]], calcDiff); Flokzu.onChange([[Hora 2]], calcDiff); ``` | La salida de este script tiene formato "HH:mm:ss" pero es totalmente configurable (Ejemplo: "HH:mm" para no mostrar los segundos transcurridos). **Resultado** ![](https://storage.crisp.chat/users/helpdesk/website/-/c/c/c/3/ccc3fbb5dc442800/hora-resta_1nl9pc7.png) ### Validar si el valor de un campo "Fecha" es menor a la fecha actual En ocasiones queremos realizar algún tipo de comprobación con las fechas ingresadas en los campos de tipo Fecha de Flokzu. En este caso, si queremos que al presionar un botón se compruebe si la fecha ingresada es menor a la fecha actual y en caso contrario lanzar un error y no permitir avanzar, los pasos a seguir son los siguientes: **Paso 1** Agregar un campo de tipo Fecha (Ejemplo: "Fecha 1"). **Paso 2** Vamos a la sección de configuración de visibilidad y scripts y allí dentro a "Scripts" **Paso 3** Definimos el siguiente script en la tarea que nos interese. ```javascript function verificarFecha(msg, button){ if(button == 'Aprobar'){ // Nombre del botón que ejecutará la verificación // Obtener los datos ingresados var fechaIngresada= dateFns.parse(Flokzu.getFieldValue([[Fecha 1]]), 'yyyy/MM/dd', new Date()); // Obtener la fecha actual var fechaActual = new Date(); // Si la fecha ingresada es podterior a la actual, lanza un error if (dateFns.isAfter(fechaIngresada, fechaActual )){ Flokzu.error([[Fecha 1]], 'Mensaje de error personalizado'); } } } // Asociamos la función al evento de completar tarea Flokzu.onAction(verificarFecha); ``` | Hecho esto, cuando el usuario presione el botón deseado, se ejecutará el script y si la fecha seleccionada es mayor a la actual, se lanzará un error y no permitirá continuar. ### Acotar la cantidad de decimales de un número en un script Usando un Autocalculado de tipo Script, es posible realizar operaciones aritméticas que involucren varios campos de Flokzu. Por ejemplo si quisiéramos multiplicar 2 campos "A" y "B", el script sería algo como: ```javascript Flokzu.getFieldValue([[A]]) * Flokzu.getFieldValue([[B]]) ``` Si bien este script funciona y es válido, es posible que al multiplicar números con decimales el resultado contenga una cantidad infinita de decimales. Para evitarlo, podemos modificar la función de la siguiente manera y acotar los decimales a 3. ```javascript ( Flokzu.getFieldValue([[A]]) * Flokzu.getFieldValue([[B]]) ).toFixed(3) ``` || Cambiá "3" por el número de decimales que quieras.