Desarrollo de Scripts en Flokzu
Introducción
En Flokzu sabemos que 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.
Teniendo esto en mente desarrollamos 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 utilizando un lenguaje ampliamente reconocido como JavaScript.
Los scripts en Flokzu se deben definir utilizando el lenguaje de programación JavaScript y puede aprovecharse todo el potencial que el mismo 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.
Metodología de desarrollo
La metodología de desarrollo para los scripts en Flokzu es bastante simple. La lógica debe definirse dentro de distintas funciones JavaScript y luego asociar esas funciones con distintos eventos (campo cambia su valor, se presionó un botón, etc) a través del uso de los "listeners" (ver más abajo).
Las funciones definidas, internamente pueden hacer uso de operaciones de visibilidad, manejo de errores o lectura/escritura de campos, la librería Moment.js o jQuery, entre otras funcionalidades.
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]]
Por último es necesario aclarar que 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.
Funciones disponibles
"Listeners"
IMPORTANTE: 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.
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.
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).
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.
Flokzu.onInit( NombreFuncion);Visibilidad
IMPORTANTE: 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
Flokzu.setHidden( [[campo]] );Hacer que un campo sea solo lectura
Flokzu.setReadOnly( [[campo]] );Hacer que un campo sea editable (no requerido)
Flokzu.setEditable( [[campo]] );Hacer que un campo sea requerido
Flokzu.setRequired( [[campo]] );Lectura/Escritura de campos
IMPORTANTE: 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.
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" y "Tabla" que no están soportados por el momento.
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.
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.
Flokzu.error( [[campo]] , "mensaje" );Otros/Utiles
Obtener el usuario actual (email)
El correo del usuario que está logueado en el sistema
Flokzu.currentUser();Obtener los usuarios asignados
Retorna nombre y correo de los usuarios o el rol asignado a la tarea
Flokzu.getCurrentAssignees();Obtener Fecha actual
Retorna la fecha actual, de acuerdo a la zona horaria de la cuenta, y el formato de fecha definido
Flokzu.getCurrentDate();Obtener Hora actual
Retorna la hora actual, de acuerdo a la zona horaria de la cuenta, y en formato HH:mm:ss
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
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.
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.
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.
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
Moment.js
Flokzu incorpora la librería Moment.js (https://momentjs.com/) para el manejo de fechas/horas. La versión incluida es la 2.22.2 y puede utilizarse por completo en los scripts de formulario para todo lo que tenga que ver con cálculo de fechas. Puede combinarse con getFieldValue.
Ejemplo: moment( Flokzu.getFieldValue([[Campo Hora]]) , "HH:mm:ss");Sweet Alert
Flokzu incorpora la librería SweetAlert (https://sweetalert.js.org) 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: swal( {type : 'error' , title : 'Error!' , text: 'Mensaje de error'} );jQuery
Flokzu incorpora la librería jQuery (https://jquery.com), la cual permite realizar un sin fin de operaciones/funciones. La versión incluída es la 3.5.0 y puede utilizarse para diversas tareas/atajos, desde realizar llamadas Ajax,
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 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.
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.
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 funcion tanto para onChange como onAction, e intermanente distinguimos si se trata de un action (sender == evt_ruteo) o un onChange simplemente.
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 Moment.js 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
calcDiff();
function calcDiff(){
var start = moment( Flokzu.getFieldValue([[Fecha 1]]) , "YYYY/MM/DD");
var end = moment( Flokzu.getFieldValue([[Fecha 2]]) , "YYYY/MM/DD");
var weekdayCounter = 0;
while (start <= end) {
if (start.format('ddd') !== 'Sat' && start.format('ddd') !== 'Sun'){
weekdayCounter++; //add 1 to your counter if its not a weekend day
}
start = moment(start, 'YYYY-MM-DD').add(1, 'days'); //increment by one day
}
return weekdayCounter;
}Script considerando días de corrido
calcDiff();
function calcDiff(){
var m1 = moment( Flokzu.getFieldValue([[Fecha 1]]) , "YYYY/MM/DD");
var m2 = moment( Flokzu.getFieldValue([[Fecha 2]]) , "YYYY/MM/DD");
return Math.abs(m1.diff(m2, 'days')) + 1;
}Restar dos campos de tipo "Hora" con un campo Autocalculado
Con Flokzu crear un campo autocalculado que en todo momento muestre la diferencia (en horas) entre 2 campos tipo "Hora" es muy simple. Para ello utilizaremos la librería Moment.js que Flokzu ya tiene incorporada.
Paso 1
Agregar 2 campos de tipo Hora (Ejemplo: "Campo 1" y "Campo 2").
Paso 2
Agregar un campo autocalculado (Ejemplo: "Resta")
Paso 3
Agregar el script al autocalculado
calcDiff();
function calcDiff(){
var m1 = moment( Flokzu.getFieldValue([[Campo 1]]) , "HH:mm:ss");
var m2 = moment( Flokzu.getFieldValue([[Campo 2]]), "HH:mm:ss");
if(m1.isBefore(m2)){
return (moment.utc(m2.diff(m1)).format("HH:mm:ss"));
}else{
return (moment.utc(m1.diff(m2)).format("HH:mm:ss"));
}
}La salida de este script tiene formato "HH:mm:ss" pero es totalmente configurable (Ejemplo: "HH:mm" para no mostrar los segundos transcurridos). Para más información acudir a la documentación de la librería Moment.js
Notar que no se definió ningún "listener" ya que al ser un autocalculado los listeners son inferidos por el motor de scripts de Flokzu automáticamente.
Resultado
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.
function verificarFecha(msg, button){
if(button == "Nombre del boton que nos interesa"){
// Obtenemos la fecha ingresada
var fechaIngresada = moment(Flokzu.getFieldValue( [[Fecha 1]] ) , "YYYY/MM/DD" );
// Obtenemos la fecha actual
var fechaActual = moment();
// Si la fecha ingresada es mayor a la actual lanzamos error
if(fechaIngresada.isAfter(fechaActual)){
Flokzu.error([[Fecha 1]], "Aqui el mensaje de error personalizado");
}
}
}
//linkeamos la funcion verificarFecha a el clickeo de un botón
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:
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.
( Flokzu.getFieldValue([[A]]) * Flokzu.getFieldValue([[B]]) ).toFixed(3)Cambiá "3" por el número de decimales que quieras.
Actualizado el: 13/05/2022
¡Gracias!