3.4/RealizarPersonalizaciones/Jasper
Sumario
Personalizar las salidas !JasperReports
A continuación se detallan los pasos necesarios para realizar la personalización de una salida Jasper. Se toma como ejemplo la etapa de Solicitud de Bienes y Servicios, salida de la operación Ver solicitud.
1. Copiar archivos de etapa/salida
La estructura de los reportes o salidas construidas en Jasper constan de varios archivos. Tomando como ejemplo la etapa Solicitud de Bienes y Servicios:
Image(dia_ejemplo_solicitud_suministro.png)
se puede apreciar en la imagen los archivos que conforman la salida Ver solicitud, están ubicado en la ruta /ruta_instalacion/diaguita/aplicacion/jasper/solicitud_suministro/ y se componen de:
* ci_ficha_solicitud_suministro.jrxml: es el código fuente del reporte maestro, el archivo que será necesario editar para personalizar dicha salida. * ci_ficha_solicitud_suministro.jasper: es el reporte compilado el cual ejecutará la aplicación SIU-Diaguita al ingresar a Ver solicitud. * ci_ficha_solicitud_suministro: es un directorio que almacena las partes individuales de la salida, denominados subreportes (los subreportes son también archivos .jrxml y .jasper). Pueden existir uno o varios subreportes, que son invocados desde el reporte maestro. Este directorio es opcional y solo existe si existen subreportes.
Nota: los archivos solicitud_suministro_anexo restantes se corresponden a la salida Ver anexo de dicha etapa.
Para poder personalizar la salida Ver solicitud, será necesario copiar el archivo ci_ficha_solicitud_suministro.jrxml y la carpeta ci_ficha_solicitud_suministro con todo su contenido hacia la ruta de personalización /ruta_instalacion/diaguita/aplicacion/personalizacion/jasper/solicitud_suministro/. Cabe aclarar que se excluyuen los archivos .jasper pues se trata de los archivos compilados que se producirán posteriormente con la herramienta iReport. Para finalizar, al trabajar sobre el diseño del reporte, es necesario copiar todos estos archivos también en el equipo local donde se utilizará la herramienta iReport para luego subir los cambios al directorio de personalizaciones en el servidor.
1.1 hoja de estilos globales
Para facilitar la tarea de personalizar los estilos generales de las salidas (bordes, tipografías y tamaño de letas, etc.), se proporciona una hoja de estilos llamada diaguita_estilo.jrtx ubicada dentro del directorio jasper. Tanto si la editamos o no, es necesario copiar dicho archivo hacia el directorio /ruta_instalacion/diaguita/aplicacion/personalizacion/jasper/ pues es requerido por cada uno de los reportes.
2. recuperar archivo de datos XML
Para facilitar el diseño, realizar pruebas y ajustes, al ingresar a cualquier salida del sistema SIU-Diaguita se exporta a un archivo XML los datos que fueron utilizados por la salida en cuestión. De esta forma, es posible utilizar la herramienta iReport para el diseño de los reportes. Los archivos XML se almacenan en la ruta /ruta_instalacion/diaguita/aplicacion/temp/ireport respectivamente y mantienen el formato:
donde el nombre ci_ficha_solicitud_suministro se corresponde con el nombre del archivo físico usado en la salida (el reporte maestro) y lo que se proporciona entre paréntesis corresponde a información contextual extra para identificar entre distintos registros de la misma salida (número, año, etc.). Copiar este archivo en el equipo local donde se trabajará con la herramienta iReport.
3. configurar el diseñador iReport
La herramienta iReport permite diseñar, realizar cambios en forma visual, previsualizar y ejecutar los reportes que componen las salidas. Se debe descargar la versión 5.1 desde el sitio web del proyecto.
Nota: la versión 5.1 es requerida debido a la compatibilidad de los reportes y las librerías !JasperReports usadas por SIU-Diaguita.
3.1 configurar la conexión de datos
Para ser capaces de previsualizar las salidas con iReport, es necesario configurar una conexión al archivo XML de datos obtenido en el [#a1.Copiararchivosdeetapasalida paso 1]. Para ello, se debe seleccionar el ícono de conexiones (estilo base de datos con una flechita) y seguir el asistente paso a paso:
Image(Dia_01-conexion_nueva.png)
Se debe seleccionar el tipo de conexión XML file datasource.
Image(dia_02-conexion_tipo.png)
En Name se debe cargar un nombre representativo para la conexión y que permita asociarla con la etapa y salida puntual (como SBS - Ver solicitud); en XML File se selecciona el archivo XML de datos; se debe tildar la opción Use the report XPath expression when filling the report;
Una vez ingresados estos valores es posible realizar un Test de la conexión para determinar si esta todo correcto y proceder a guardar la configuración.
Image(dia_04-conexion_test.png)
Por último, cada vez que se crea una conexión o se trabaja con un reporte diferente, hay que cerciorarse de que la conexión activa sea la correcta. Podremos tener múltiples conexiones a diferentes archivos XML pero solo una estará activa.
Image(dia_06-conexion_activa.png)
4. personalizar con iReport
Para comenzar la personalización, se debe tener en el equipo local la copia del directorio /ruta_instalacion/diaguita/aplicacion/personalizacion/jasper. Una vez copiados los archivos, con iReport se debe abrir el reporte maestro ci_ficha_solicitud_suministro.jrxml.
Image(dia_07-reporte_maestro.png)
Sobre el reporte maestro (archivo ci_ficha_solicitud_suministro.jrxml) es posible personalizar el encabezado, pié de página, márgenes, título y logo respectivamente.
Todos los reportes maestros están compuestos de bandas de detalles (Detail n) asociadas físicamente a subreportes. Para proceder a editar el subreporte de ITEMS SOLICITADOS, se debe seleccionar la banda Detail 2 y con el click secundario Open subreport. Esto abrirá una nueva pestaña con el subreporte en cuestión.
Una vez en el subreporte, se pueden hacer cambios y ajustes localizados. Sin embargo, la opción de Preview no funionará cuando se trabaje sobre un subreporte, ya que la configuración realizada exige compilar y previsualizar desde el reporte maestro únicamente.
Gracias a que se ha establecido una conexión de datos (ver [#a3.1configurarlaconexióndedatos paso 3.1]), es posible acceder sobre el subreporte a la opción Report Query y previsualizar la estructura XML junto con los datos de la salida.
Image(dia_09-report_query.png)
En dicha pantalla, navengando hasta el path /solicitudes/solicitud/item_solicitados/registro se selecciona el atributo @desc_rubro y con el click secundario se elige la opción Add node as a field. Esto creará un campo nuevo para poder visualizarlo. (Nota: es posible crear este campo copiando uno existente desde el Report inspector, como @unidad_medida y ajustando adecuadamente el nombre y el valor de la propiedad description).
Teniendo el campo creado, se procede a desplazar la columna Descripción para que sea posible seleccionar desde el Report inspector el campo @desc_rubro y arrastrar y soltarlo en la posición deseada. Se debe ajustar y arrastrar el elemento para que se adapte a la posición deseada. En las propiedades del elemento, se pueden modificar diversos atributos, como ser el nombre o descripción que visualiza.
Nota: el diseño mostrará en todo momento si los campos se solapan uno con otro mediante un ícono triangular de admiración.
Image(dia_11-previsualizar.png)
Para probar los cambios, es necesario guardar todos los cambios, compilar y dirigirse a la pestaña del reporte maestro (archivo ci_ficha_solicitud_suministro.jrxml) donde se seleccionará la opción Preview para ingresar en el modo de previsualización.
Nota: esta opción Preview por defecto procede a compilar el reporte, siempre que se haya modificado. Es recomendable verificar que la compilación se realizó con éxito.
Se observa la nueva columna Rubros del cuadro ITEMS SOLICITADOS.
Para finalizar el cambio, es necesario seleccionar la opción Designer para volver al modo de edición y seleccionando cada uno de los elementos que se agregaron para ajustar su propiedad style acorde a la presente en los otros elementos que componen el cuadro.
4.1 personalizar los estilos globalmente
Todos los reportes y subreportes de SIU-Diaguita utilizan la propiedad style para aplicar ciertas configuraciones de forma organizada: fuente y tamaño, alineación de títulos y subtítulos, estilos regular y cursiva, bordes y colores, etc. En general, para realizar un cambio de tipografía que afecte a todas las salidas, basta con personalizar el archivo diaguita_estilo.jrtx que tiene que estar presente en el directorio de personalización de Jasper.
Image(dia_13-style_maestro.png)
Una vez abierto, se debe utilizar la opción Template inspector para visualizar y navegar entre los distintos estilos disponibles. Seleccionando por ejemplo reporte_titulo se puede apreciar en la paleta de Properties los atributos que definen la tipografía: size 20, bold (negrita), etc.
Nota: un estilo es utilizado mediante la propiedad style. Es posible que un elemento de diseño cuente con el estilo asignado, pero que sobreescriba localmente algún valor específico (como ser fuente o alineación). En estos casos, siempre se impone el último valor.
5. Subir y probar personalización
Una vez se haya desarrollado los ajustes necesarios a la salida, solo será necesario subir los archivos al directorio /ruta_instalacion/diaguita/aplicacion/personalizacion/jasper en la etapa correspondiente. Se deben copiar los archivos .jrxml como .jasper respectivamente.
De esta forma, el sistema ya se encuentra en posición de trabajar con los reportes personalizados. !JasperReports no requiere ser reiniciado para que los cambios tomen efecto. Se recomienda correr las salidas personalizadas sobre entornos de prueba, que permita exponerlos a una variedad y combinación de datos mayor sin comprometer el entorno de producción.
5.1 depurar errores en iReports
La mayor parte del tipo, la depuración consiste en visualizar los erroes de diseño, compilación y/o ejecución en la misma herramienta iReport. Para ello, se debe desplegar la ventana iReport Output que muestra por lo general una excepción al estilo del lenguaje de programación Java. En el 90% de los casos, la frase Caused by: ... indica exactamente el error en cuestión.
Image(dia_14-debug_ireport.png)
Por otro lado, un error que suele aparecer y afecta solo al entorno iReport es cuando se utiliza Java versión 1.6 (debido a un bug presente en dicho SDK, no funciona a menos que se utilice la versión 1.7).
5.2 depurar errores en producción
En algunos casos, los errores que se producen son debido a una disparidad del entorno de diseño de los reportes y el de producción, problemas de librerías, etc. En estos casos, es posible acceder al log de ejecución del servicio Jasper para evaluar posibles inconvenientes. Por defecto, el script de inicio diaguita_reportes.sh del servicio Jasper crea el archivo /var/log/diaguita_reportes.log que registra todos los errores y mensajes.
Otro error común esta relacionado con las tipografías que se utiliza al momento de diseñar una salida, o si la tipografía viene definida en el contenido de una salida (por ejemplo, los artículos de un pliego suelen textos copiados externamente del sistema y pegados sin mayores precauciones). En estos casos, se suele producir un error similar a:
La solución consiste en instalar las fuentes a utilizar, tanto en el servidor como en el ambiente de desarrollo de la personalización. Para ello, hay que recurrir a las herramientas propias del SO que esten usando (por ej en Debian GNU/Linux).
Otro camino puede ser la configuración del servicio !JasperReports para que ignore la falta de tipografía y no termine con un error abruto. Para ello existe una propiedad que se puede configurar en !JasperReports de dos formas:
* abrir el jarPara finalizar, reiniciar el servicio diaguita_reportes. En cualquiera de estos casos, lo que se hace es ignorar la fuente (al menos en el servidor) con lo que ello conlleva a que en sus entornos locales al utilizar el diseñador les falle o no (si tienen misma configuración o si tienen efectivamente la fuente). Lo ideal sería tener todas las tipografías instaladas siempre, junto con un mínimo compromiso de no copiar/pegar de forma directa contenido de la web (es recomendable usar un editor ofimático intermedio y normalizar).
Anexo: agregar una salida propia
Si se desea construir reportes o salidas propias y específicas, y que no están relacionados con las salidas existentes de SIU-Diaguita, corresponde crear una salida propia. El mecanismo utilizado implica realizar modificaciones a diversos archivos PHP, por lo que se recomienda trabajar en conjunto con un esquepa de desarrollo de personalizaciones propias (como el que se define en la sección Personalizar php y metadatos) a fin de mantener los cambios entre distintas versiones del sistema.
1. Determinar la etapa/ficha donde se debe ubicar la nueva salida
Es de suma importancia establecer este punto, ya que afecta a la ubicación de los archivos o plantillas de las salidas, a la zona particular y al juego de datos inicial con el cual se trabajará.
Se tomará como ejemplo agregar una nueva salida en la Ficha de convocatoria S/N para la etapa Convocatorias, llamada "Mi salida". A partir de este punto, sabemos que dicha etapa está relacionada con los siguientes directorios:
*Además, los datos iniciales (en formato XML se entiende) estarán compuestos por los que se obtienen del CN de la etapa en cuestión. En este caso, se corresponde a los datos visualizados en la operación Ver datos XSL disponibles únicamente bajo el título Datos comunes a todas las impresiones de: convocatoria así como lo que aparezca posteriormente bajo a el título Datos específicos para la impresión: mi_salida (al finalizarse el paso 3 se puede agregar datos extras, a partir de ese punto serán visibles).
2. Crear template de la nueva salida
Para este ejemplo, los templates de la nueva salida Jasper se tendrán que crear en el directorio3. Establecer boton de generación de la salida
Los botones que permiten lanzar la salidas (también conocidos como operaciones), se definen en los archivos de zonas existenes por cada etapa. Para este ejemplo, se trata del archivo$this->generar_boton_salida($this->editable_id, 'mi_salida', 'Mi salida');
$vinculos = array(
....
'mi_salida' => "$base&xsl_archivo_plantilla=mi_salida&XSL__dao_convocatoria__get_renglones_rubros_convocatorias=id_convocatoria||$identificador"
);
&action=edit&redlink=1){kind=link}
&action=edit&redlink=1){kind=link}
&action=edit&redlink=1){kind=link}
&action=edit&redlink=1){kind=link}
&action=edit&redlink=1){kind=link}
&action=edit&redlink=1){kind=link}
&action=edit&redlink=1){kind=link}
&action=edit&redlink=1){kind=link}
&action=edit&redlink=1){kind=link}
&action=edit&redlink=1){kind=link}
&action=edit&redlink=1){kind=link}
&action=edit&redlink=1){kind=link}
&action=edit&redlink=1){kind=link}