GeneXus - HugaoBulkActionsManager - User Control/Module-Extension

HugaoBulkActionsManager es un control que permite interactuar con procedimientos ejecutados en forma desatendida mediante el comando Submit en GeneXus. Permitiendo así un mejor feedback para el usuario final.

El control está desarrollado para GeneXus 16, y ha sido testeado hasta el upgrade 11

Es un control que se compone de 2 partes:

• UserControl Web (Responsive o no)
• Module empaquetado en GeneXus para notificación al User Control.

El propósito de este control, es poder ir informando el avance de procesos desatendidos ejecutados hacía el servidor utilizando el llamado submit de GeneXus, dando así un mejor feedback al usuario final sin bloquear el hilo principal de la aplicación permitiendole seguir trabajando en otros procesos mientras espera que termine la acción pesada ("Bulk Action").

Este control requiere que la aplicación que lo va a utilizar tenga implementados y pueda usar Web Sockets

Instalación

Una vez descargados los recursos, encontrará:

1. Un folder comprimido llamado HugaoBulkActionsManager.zip, descomprimalo y copielo en la ruta de instalación de GeneXus <PathGeneXus>\UserControls y después ejecute desde la línea de comandos el comando <PathGeneXus>\GeneXus /install.

2. Un archivo llamado HugaoManagerBulkActions_<version>.opc copiarlo dentro de la carpeta <PathGeneXus>\Modules para que nos aparezca en la ventana de Manage Module References dentro de GeneXus (no es obligatorio hacerlo de esta manera, también se puede cargar por la opción en Local -> Upload from file en el mismo Manage Module Reference).

Uso

Para utilizar el control, arrastre desde el Toolbox de GeneXus el control HugaoBulkActionsManager hacía el Webpanel o MasterPage donde quiera ubicarlo (lo recomendable es utilizarlo en la MasterPage para generalizarlo en la aplicación completa)

El control en sus propiedades cuenta las siguientes que sirven para configurar un feedback auditivo/visual:

• Play Audio On Completed: Sus posibles valores son True o False y define si el control web debe reproducir un sonido cuando reciba una notificación de que el bulk action ha terminado.
• Play Audio On New Task: Sus posibles valor son True o False y define si el control web debe reproducir un sonido cuando reciba un notificación de un bulk action nueva.
• Use Desktop Notification: Sus posibles valores son True o False y define si el control web mostrará  notificaciones visuales de escritorio.
• Desktop Notification On New Task: Sus posibles valores son True o False y define si el control web mostrará notificaciones cuando reciba una notificación de un bulk action nueva.
• Desktop Notification On Completed: Sus posibles valores son True o False y define si el control web mostrará notificaciones cuando reciba una notificación de que el bulk action ha terminado.
• DesktopNotificationTimeout: Define el tiempo que se visualizará la notificación mostrada (auto-cerrado), el valor se debe especificar en mili-segundos, puede especificarse valor de 0 para no auto cerrar la notificación, pero debe tener en cuenta que los navegadores eventualmente ocultaran la notificación, sin embargo si utiliza Google Chrome, la notificación quedará agregada en las notificaciones de windows, si define 0 como valor de esta propiedad.
• MainIconImage: Esta propiedad define si desea utilizar un icono diferente al default que viene con el control y que se pinta en el objeto web según donde se agregue el control, por defecto es un reloj de arena. Si desea configurar una imagen personalizada deberá especificar una URL valida de la imagen. Puede asignarse una URL de la KB desde el evento Start utilizando: HugaoBulkActionsManager.MainIconImage = Link(!"NombreImagenEnKB"). Tenga en cuenta que  si define una URL que no tenga el mismo protocolo que su aplicación (HTTP y/o HTTPS) los navegadores pudiesen bloquear la carga de este recurso por considerarlo contenido mixto.

Agregando el control al objeto, este ya está disponible y escuchando las notificaciones que los procedimientos submit le envíen.

Ahora para poder notificar adecuadamente al control es necesario utilizar el módulo que se agregó desde el Manage Module References, una vez agregado a la KB en la parte de Reference en el KB Navigator le saldrá un nuevo paquete llamado HugaoManagerBulkActions.

En el módulo podrá ver un SDT que describe la información de la acción bulk que se va a notificar, la estructura es:

• Id: Es la identificación única de la acción que se está ejecutando, con este indicador el control en pantalla será capaz de actualizar y/o mostrar el avance de la misma para el usuario.
• Description: Es el texto  que se le irá mostrando al usuario por ejemplo "Generando archivo plano", este texto puede ser actualizado en cada notificación que se le haga al control.
• ProgressType: Es un indicado basado en un dominio disponible también en el módulo llamado HugaoManagerBulkActions.ProgressIndicatorType cuyos valores disponible son: 
• Indeterminate (I): Le indica al control web que el proceso llamado con submit no va a reportar el porcentaje de avance sino su inicio y su final, por lo que el control web mostrará un icono de progreso ideterminado.
• Determinate(D): Le indica al control web que el proceso llamado con submit va a reportar el porcentaje de avance por lo que el control pintará un icono de progreso que se actualizará conforme se le vaya notificando.
• Value: Es el valor actual del progreso, es importante enviarlo cuando se notifica de forma Determinate para que en pantalla se pueda apreciar el avance del progreso, es necesario siempre al finalizar el proceso enviarlo con valor 100 para que el control sepa que ese proceso llegó a su fin, y pueda notificar al usuario final.
• StartDate: Es la fecha y hora en la que inicia el proceso, este dato se mostrará en el panel de acciones en pantalla. Esta basado en un dominio BAIDateTime pero recibe cualquier valor DateTime.
• CompleteDate: Es la fecha y hora en la que finaliza el proceso, este dato se mostrará en el panel de acciones en pantalla. Esta basado en un dominio BAIDateTime pero recibe cualquier valor DateTime.
• LinkOnComplete: Define si el control debe mostrar una acción para que el usuario pueda acceder a una pantalla una vez el proceso/acción bulk termine. Se puede dejar sin asignar en caso de que no se requiera dar acceso a alguna pantalla.
• LinkDescription: Si se ha definido un link, puede definir un mensaje que se muestre al usuario en lugar del link por ejemplo "Descargar aquí".
• LinkTarget: Si se ha definido un link, puede definir el target destino del mismo, los valores posible son los soportados por la etiqueta HTML A por ejemplo "_blank".

También se encontrará un procedimiento llamado NotifyUpdateProgress que servirá para que el procedimiento llamado con submit pueda notificar al control acerca del estado de la acción que está ejecutando, recibe como parámetro el SDT descrito anteriormente.

También se encontrará un External Object que permitirá escuchar un evento web cuando el usuario de clic en una notificación de escritorio (para poder usarlo deberá activar las notificaciones de escritorio - Use Desktop Notification)

Resultado Final

User Control final

Soporte otros Idiomas

El control utiliza unos textos estáticos en la parte web para que el feedback hacia el usuario final sea más intuitivo. Los textos estáticos por defecto se muestran en español y son los siguientes:

• Limpiar todo: Este mensaje se visualiza cuando en el panel de acciones se encuentre por lo menos una visualizándose, adicional tiene un evento clic que al utilizarlo eliminaría todas las acciones visualizadas en el manager.
• Ejecutándose: Este texto se muestra a forma de "titulo" en cada acción visualizada en el manager y se mostrará siempre que la acción no se le haya notificado que se ha completado.
• Completado: Este texto se muestra a forma de "titulo" en cada acción visualizada en el manager cuando se le ha notificado que la acción ha concluido.
• Mostrar Detalles: Este texto se muestra para visualizar el detalle de fecha de inicio y fecha final del proceso, se muestra cuando los detalles estén ocultos y tiene un evento clic que muestra los detalles mencionados.
• Ocultar Detalles: Este texto se muestra para ocultar el detalle de fecha de inicio y final del proceso, se muestra cuando los detalles se estén mostrando y tiene un evento clic que oculta los detalles mencionado.
• Iniciado el: Este texto se usa para acompañar la fecha y hora de inicio del proceso.
• Completado el: Este texto se usa para acompañar la fecha y hora de finalización del proceso.
• Tarea masiva agregada: Este texto se usa como titulo en la notificación de escritorio cuando se tienen activas y configurada para mostrar notificaciones para nuevas tareas.
• Tarea masiva completada: Este texto se usa como titulo en la notificación de escritorio cuando se tienen activas y configurada para mostrar notificaciones para tareas completadas.

Igualmente el control soporta la traducción de estos textos estáticos utilizando el objeto Language de GeneXus, puede abrir el o los objeto(s) Language que utilice en su KB y agregar los siguientes mensajes con el texto que desee se visualice en la parte web:

• Limpiar todo: Agregue el mensaje HBAM_ClearAll a los objetos Language que utilice en su KB.
• Ejecutándose: Agregue el mensaje HBAM_Runing a los objetos Language que utilice en su KB.
• Completado: Agregue el mensaje HBAM_Ended a los objetos Language que utilice en su KB.
• Mostrar Detalles: Agregue el mensaje HBAM_ShowDetails a los objetos Language que utilice en su KB.
• Ocultar Detalles: Agregue el mensaje HBAM_HideDetails a los objetos Language que utilice en su KB.
• Iniciado el: Agregue el mensaje HBAM_StartedOn a los objetos Language que utilice en su KB.
• Completado el: Agregue el mensaje HBAM_CompletedOn a los objetos Language que utilice en su KB.
• Tarea masiva agregada: Agregue el mensaje HBAM_NotificationTitleAdded a los objetos Language que utilice en su KB.
• Tarea masiva completada: Agregue el mensaje HBAM_NotificationTitleCompleted a los objetos Language que utilice en su KB.

Por favor verificar que al agregarlo y especificar, GeneXus actualice los archivos del idioma y agregue efectivamente los nuevos datos.

Compatibilidad con WWP

Se detecta que si en la KB que se quiere utilizar el control también se está usando el pattern WWP las plantillas de este pattern puede afectar el efecto visual del control, por favor para solucionarlo asegúrese de estar usando como mínimo la versión 1.00.08 del control HugaoBulkActionsManager.

Abra el objeto Theme que está utilizando en su KB y creé una nueva clase con el nombre que deseé bajo el nodo TableCell.

Con los siguientes valores en las propiedades.

Margin Top asignar valor de 15px

Margin Right asignar el valor de 5px

Custom Properties asignar el valor de line-height: 0;

Puede modificar las propiedades de Margin Top y Right según necesite.

Esta clase  nueva se la asignaremos al User Control de la Master Page en la propiedad Cell Class.

Ahora nuevamente en el Theme agregamos una clase en el nodo custom que se llame: hugao-bulkactions-main-button>span y contenga la siguiente propiedad:

Custom Properties asignar el valor de padding-top: 7px !important;

Con estos cambios ya debería visualizarse bien el control en pantalla.

Ejemplo de Uso

Importante: El objetivo de este ejemplo es mostrar de la forma más clara el uso del control, puede que algunas cosas sean más optimas programarlas de otra forma.

En nuestra master page agregamos el control a donde queramos que se visualice, siguiendo los pasos del apartado Uso descrito más arriba en este artículo. 

A continuación creamos un webpanel y nos aseguramos de que este panel tenga configurado en la propiedad Master Page la master page a la que le hemos agregado el control.

Declaramos en el webpanel una variable llamada ProgressType de tipo ProgressIndicatorType, HugaoManagerBulkActions y la agregamos en pantalla junto con un botón al cual le asignaremos un evento 'Enviar', deberíamos tener algo similar a lo siguiente:

Ahora creamos un nuevo procedimiento al cual invocaremos mediante el llamado sumbit desde el webpanel creado anteriormente.

La idea a manera de ejemplo es simular la creación de un documento de texto "exportado" de datos y retro-alimentar al usuario cuando termine y que lo pueda descargar, para ellos empezamos con definir la identidad del bulk action, lo podemos hacer de la siguiente manera:

Llenamos la información del SDT de información de la acción, acá lo importante es que asignemos un Id único para la acción, un ejemplo de hacerlo es utilizando las funciones de GUID de GeneXus. Y se notifica al UC web utilizando el procedimiento NotifyUpdateProgress que lo encontraremos en el módulo empaquetado que se importó a través de la extensión .opc que se descargó como se describe en los pasos más arriba en este artículo.

A continuación haga un proceso "pesado" que se demore o ponga un Sleep con algunos segundos (para motivos de ejemplo), en nuestro caso crearemos un archivo de texto en el folder de temporales y le escribiremos un par de líneas, luego esperaremos unos segundos y notificaremos nuevamente al control web utilizando el mismo procedimiento y SDT que inicializamos en el paso anterior, simplemente actualizando el valor de la propiedad Value del SDT, que existe progreso, quedaría algo como lo siguiente:

Podemos repetir el fragmento de código que escribe lineas en el archivo a forma de hacer el proceso más pesado y demorado (como ejemplo), y actualizando el valor del progreso y notificando en cada vez al control web, nos quedaría algo similar a:

Antes de notificar por última vez al control web, actualizamos el resto de propiedades, para dar más información, como por ejemplo la fecha de finalización del proceso, y un link donde se puede descargar el archivo que se ha generado en el proceso, esto último es una buena ayuda pues el usuario final de su sistema, podría descargar directamente el archivo sin tener que salir de la pantalla donde esté en el momento que el proceso termine. Nos quedaría algo similar a:

El este caso utilizo un procedimiento de mi autoría que forza una descarga HTTP de una archivo (será un nuevo post) pero en la wiki de GeneXus pueden encontrar un ejemplo similar que hace la misma descarga, el link también puede ser un objeto web donde se pueda ver el resultado de un cargue masivo por ejemplo.

Ya solo queda agregar el llamado desde el webpanel a este procedimiento pesado (bulk action), para eso lo hacemos de la siguiente manera.

Le hemos pasado la variable ProgressType al procedimiento para que se pueda probar con el mismo procedimiento los dos tipos de progresos en el control.

Con esto ya pueden ejecutar y probar este nuevo control que espero sirva mucho para mejorar la UX de las aplicaciones hacía el usuario final.

También pueden ver en acción el control en el siguiente enlace: 

Ejemplo Java

Changelog

22/09/2020 - v.1.00.09 - Se agregan dos propiedades al control: -MainIconImage y -DesktopNotificationTimeout para mejorar la UX y UI.

17/09/2020 - v.1.00.08 - Se corrige diseño del panel contenedor de acciones para ser compatible con diseños del pattern work with plus.

17/09/2020 - v.1.00.08 - Se quitan sombras en el icono principal y en el botón de cerrado del panel contenedor de acciones para lograr un diseño más natural.

14/09/2020 - v.1.00.07 - Se agrega soporte para notificaciones de escritorio, configurable a través de las propiedades: -UseDesktopNotification -DesktopNotificationOnNewTask -DesktopNotificationOnCompleted estas propiedad tendrán un valor de False por defecto para dar compatibilidad de UX a la versión anterior.

14/09/2020 - v.1.00.07 - Se agrega External Object al módulo HugaoManagerBulkActions llamado Manager para escuchar un evento web cuando el usuario final da clic en la notificación de escritorio.

09/09/2020 - v.1.00.06 - Versión Inicial.