HOW TO: Scripts de validación y personalización

De Thubanpedia
Saltar a: navegación, buscar


¿Qué es Scripting de clases documentales?

El scripting de clases documentales es un mecanismo por el cual se permite la personalización de la aplicación. El scripting de clases documentales permite entre otras cosas:


- Establecer valores particulares, máscaras o validaciones excepcionales a campos de la clase documental.

- Ejecutar acciones relacionadas a eventos. Por ejemplo, enviar un mail cuando se agregue una nota a un documento.

- Modificar la apariencia de la interfaz de usuario: cambiar tipografía, color de fondo, habilitar/deshabilitar campos, etc.

- Establecer dependencia entre campos. Por ejemplo, si el campo A tiene el valor “Si” se habilita el campo B.

- Invocar servicios del sistema: guardar otro documento, generar una nota para un documento.

- Ejecutar un Stored Procedure de la base de datos.

- Validar datos contra otros sistemas.


La definición de scripting es por clase documental del sistema y funciona en base a una serie de eventos predefinidos que se ejecutan en determinados momentos al utilizar la aplicación.

Los eventos son:


- itemSave: Este evento es generado cuando un ítem se está por guardar. Comúnmente en este evento se aplican modificaciones a los campos o validaciones extraordinarias.

- itemLoad: Este evento es generado cuando un ítem se está por cargar. Comúnmente en este evento se aplican modificaciones a los campos, modificaciones a la interfaz de usuario, establecimiento de máscaras a los campos, etc.

- itemAfterSave: Este evento es generado cuando un ítem se guarda correctamente. Comúnmente en este evento se envían notificaciones por correo.

- itemClose: Este evento es generado cuando un ítem se cierra.

- itemLock: Este evento es generado cuando un ítem se bloquea.

- itemUnlock: Este evento es generado cuando un ítem se está por desbloquear.

- fieldGetFocus: Este evento es generado cuando un campo del documento toma control del foco.

- fieldLostFocus: Este evento es generado cuando un campo del documento pierde control del foco. Comúnmente en este evento disparan validaciones de los campos.

- uiPaint: Evento que se genera justo después de la creación del componente que nuclea todos los campos de la clase documental (aka Grid).


Además, los eventos pueden ser generados desde distintos orígenes:


- Interfaz de usuario de emisión de caratulas.

- Interfaz de usuario de creación de documentos.

- Interfaz de usuario de modificación de documentos.

- Interfaz de usuario de bandejas de trabajo.

- Interfaz de usuario de búsqueda de documentos.


Cada archivo respeta un formato particular para que pueda ser interpretado por la aplicación. Por lo tanto, su modificación externa puede traer aparejados problemas internos. De igual forma, cualquier problema ocasionado por Scripting será inmediatamente notificado por la aplicación para prevenir la integridad de la información.

Los archivos tienen extensión .bsh (bean shell) como se muestra a continuación y contienen código java en texto plano que es interpretado por la herramienta Bean Shell en tiempo de ejecución. Bean Shell es una librería open source que soporta scripting liviano en java. Para más información de bean Shell consultar http://www.beanshell.org/


¿Cómo configurar un archivo de scripting?

Para configurar el archivo de scripting, se debe almacenar el archivo con el nombre de la clase documental y extension bsh en la carpeta scripting dentro del context de la aplicación. Recordemos que el context de la aplicación es una carpeta que contiene configuraciones propias de cada instalación y no tiene una ubicación fija, sino que es accedida a través de la variable "thuban.context" del servidor de aplicaciones.


Ejemplo: ${thuban.context}\scripting\DOC_CLIENTE.bsh


¿Cómo obtener el usuario logueado?

String user = SecurityContextHolder.getContext().getAuthentication().getName();


¿Cómo acceder a un servicio de Thuban®?

Los servicios de Thuban® se acceden a través del mapa de parametros contenido en el evento de scripting. Allí es posible acceder a los siguientes servicios:


- Admin Service ("adminService")

- Resource Service ("resourceService")

- Document Service ("documentService")

- Mail Service ("mailService")

- Prescan Service ("prescanService")

- Search Service ("searchService")

- Tray Service ("trayService")

- Monitor Service ("monitorService")

- Report Service ("reportService")

- Counter Service ("counterService")


Para más información sobre los servicios consulte el Javadoc de Servicios Thuban®.


Map map = evt.getParameters(); DocumentService documentService = map.get("documentService");


¿Cómo saber que interfaz de usuario (UI) generó el evento?

Cada interfaz de usuario agrega una referencia a si misma en el mapa de parametros del evento de scripting. Cada interfaz posee su propia key. Si al recuperar esa key del mapa de parametros, la misma es distinta de nulo, entonces el evento fue generado por esa UI. Ejemplo:


Map map = evt.getParameters(); if(map.get("prescanWindow")!= null) { //EVENTO GENERADO DESDE UI DE PRESCAN } else if ("mainWindow") { //EVENTO GENERADO DESDE UI DE VISUALIZACION DE DOCUMENTOS }


Keys para cada UI


"newWindow": Pantalla de creación de nuevos documentos.

"prescanWindow": Pantalla de emisión de caratulas.

"mainWindow": Pantalla de visualización de documentos.

"searchWindow": Pantalla de busqueda de documentos.


¿Cómo obtener una referencia a un componente de UI?

Actualmente solo es posible acceder a la grilla de indices del item visualizado. Para acceder a cada uno de los campos de Input se utiliza la clase UITools a través del método estatico retrieveInputElement, que recibe 2 parametros: la referencia a la grilla de campos y el id del campo indice (como se le asignó a través de la herramienta Thuban® Admin).

Ejemplo:

Si deseo acceder al campo FORM_NOMBRE de la grilla de campos para modificar su valor:


Map map = evt.getParameters();

Grid grid= map.get("fieldsGrid");

InputElement element= grid.retrieveInputElement(grid, "FORM_NOMBRE");


element.setText("MODIFICO EL VALOR DEL CAMPO!");

Thuban® utiliza ZK para los componentes de la UI. Para mas información sobre las propiedades y métodos de cada componente consulte el Javadoc de ZK. http://zkoss.org/javadoc/3.6/zk/


¿Cómo modificar atributos de un componente de UI?

Siguiendo el ejemplo anterior, se puede utilizar la referencia al InputElement para:


- Habilitar/ Deshabilitar un componente.

- element.setReadonly(true/false);

- element.setDisabled(true/false);

- Establecer un estilo CSS (Cascade Style Sheet).

- element.setStyle("left-padding: 5px; color:red;");

- Establecer una máscara a un campo (por ejemplo, para validar que una dirección de correo contenga el formato "xxxxx@xxxx.xxx.xx").

- element.setConstraint("/.+@.+\.[a-z]+/: Please enter an e-mail address");


¿Cómo mostrar Diálogos con mensajes (Message Box)?

Para mostrar diálogos en un evento de scripting es posible utilizar la clase Messagebox de ZK que recibe diversos parametros y permite parametrizar los siguientes atributos:

- Título.

- Mensaje.

- Icono.

- Botones Posibles.


Cuando se ejecuta un dialogo de mensaje, la ejecución del evento se detiene hasta que finaliza la interacción con el usuario, lo que permite recuperar la opción elegida por el usuario.


Ejemplo: Para mostrar un diálogo con:

Título: Scripting Test

Mensaje: Fecha Invalida. Por favor ingrese una fecha posterior a 12/12/2008

Icono: Warning.

Botones: Ok.

int result= 0;

result= Messagebox.show("Bienvenido al scripting!!", "Scripting Test", Messagebox.OK | Messagebox.CANCEL, Messagebox.QUESTION);

if(result==Messagebox.OK)

{ Messagebox.show("Presionó OK", "Scripting Test", Messagebox.OK | Messagebox.CANCEL, Messagebox.INFORMATION); }


¿Cómo obtener qué bandeja de trabajo originó el evento (para workflows colaborativos)?

Actualmente no es posible acceder a la bandeja de trabajo. Se incorporará en proximas versiones.