NotasTecnicas/personalizaReportes

<< volver


Personalizar Certificados y Constancias

Guarani 3 realiza la impresión de comprobantes a partir de documentos PDF. Estos son generados a partir de JASPER, un motor de generación de reportes basado en JAVA soportado por SIU-Toba.

Para el funcionamiento del mismo se debe bajar el siguiente paquete:
 Paquete JavaBridge+JasperReports
y descomprimirlo en el directorio $toba_dir/php/3ros/.

Luego para la ejecución del motor de Jasper ejecutar el siguiente comando:

java -jar $toba_dir/php/3ros/JavaBridge/WEB-INF/lib/JavaBridge.jar SERVLET:8081

Para mas información acerca de la instalación de JASPER en el sistema consultar el TRAC de SIU-Toba:  http://toba.siu.edu.ar/trac/toba/wiki/Impresion/JasperReports

En la siguiente imagen se puede observar el funcionamiento básico de JASPER:

source:/trunk/img/FuncionamientoJASPER.jpg

Basicamente, JASPER genera el documento PDF tomando una plantilla (archivo .jasper), un conjunto de datos (un archivo XML o una conexion a la BD) y un conjunto de parametros (que normalmente son utilizados para la configuracion o encabezado del reporte).

La versión que soporta SIU-TOBA para edición de plantillas jasper (iReport) es la 5.6.
Como Documentación recomendada para el desarrollo de plantillas JASPER ver:  http://jasperforge.org/website/jasperreportswebsite/trunk/documentation.html

La personalización de constancias y certificados en Guarani 3 normalmente depende de lo que se quiera personalizar, aunque generalmente implica desarrollar una plantilla JASPER (.jasper) para la impresión del formato deseado del certificado. Para ser mas específicos, vamos a dar ejemplos prácticos para personalizar y generar nuevos certificados en el sistema.


CASO 1: Agregar un nuevo certificado

Los pasos a seguir son:

  1. Desarrollar una plantilla JASPER en iReports para el certificado en cuestión. Para realizar esta tarea se recomienda tomar como partida alguna de las plantillas proporcionadas por el sistema y realizar todas las modificaciones deseadas. Tener en cuenta las siguientes cuestiones:
  • Guardar la constancia con un nombre diferente de los existentes en el directorio : $toba_dir/proyectos/guarani/personalizaciones/exportaciones/jasper

  • La constancia (plantilla JASPER) recibe como parámetros fijos siempre el logo (path) y el nro. de solicitud (registro de la tabla sga_constancias_solicitud). Este ultimo se puede utilizar en una consulta de BD para obtener datos a mostrar en la constancia (ver constancias existentes). Recordar que además de los provistos, se pueden enviar mas parámetros que los anteriormente mencionados.

  • No hay restricción con ninguno de los objetos ni funcionalidades soportadas por la versión anteriormente mencionada de iReports (v5.6). Es importante utilizar ese editor y versión para el desarrollo del reporte, de lo contrario pueden ocurrir errores.
  1. Agregar la plantilla generada en el punto anterior al sistema a través de la operación "Administrar Plantillas". En el nombre del archivo no incluir el PATH. IMPORTANTE: Poner "Si" (valor por defecto) en el combo que indica si se permite asociar esta plantilla a una constancia para solicitud 'manual'. Como ejemplo, se recomienda analizar las constancias ya existentes en la instalación del sistema.
  1. Una Constancia o Certificado puede tener asociado un formulario donde se pidan mas datos de los que se le pasan por defecto (en caso de que sea necesario) o validaciones sobre las actividades académicas del alumno, etc. Para esto, se debe desarrollar un componente (CI) TOBA y agregar el código correspondiente. "Ver ANEXO A".
  1. Agregar la Constancia o Certificado nuevo asociándole la plantilla desarrollada y creada en el punto anterior en la operación "Administrar Constancias y Certificados" del sistema. Si se desarrollo un formulario especifico para este fin, asociarlo también mediante la operación mencionada.

CASO 2: Personalizar un certificado existente

Para dar un mayor detalle en esta tarea, a este caso lo vamos a dividir en 3 sub-casos. IMPORTANTE: Si bien como el titulo de esta sección indica, la idea de realizar esto es cambiar un certificado provisto por el sistema dándole otro formato o utilidad, para todos los casos especificados próximamente se recomienda en lugar de realizar los cambios sobre las plantillas enviadas, modificarlas desde el editor (iReport) pero grabarlas con otro nombre y agregarlas como una nueva plantilla del sistema a través de la opción "Administrar Plantillas". De esta forma se evitan conflictos con futuras versiones y actualizaciones del sistema que incluyan un cambio en las plantillas estándares.

Reemplazar la constancia o certificado provisto por el sistema por uno nuevo

Este proceso implica realizar algo similar a lo que se debe hacer cuando se desea agregar un certificado del sistema (se agrega una nueva plantilla pero en lugar de asociarla a un nuevo certificado, se la asocia a uno existente). Para esto, realizar los siguientes pasos:

  1. Realizar todos los pasos del "Caso 1" expuesto anteriormente (Agregar un nuevo certificado) a excepción del punto (4).
  1. En la operación "Administrar Constancias y Certificados" del sistema, ubicar la Constancia a remplazar y editarla eligiendo la nueva plantilla desarrollada en lugar de la que tiene asociada actualmente. ATENCION: Si la plantilla tiene un Formulario asociado, la nueva plantilla deberá tener como parámetros los que pase el formulario dinámicamente y envía a JASPER para la generación del PDF de la Constancia (lo mismo que lo señalado en el caso anterior).

Cambiar el logo o el texto de una constancia o certificado provisto por el sistema

Para cambiar el texto:

  1. Abrir la constancia que se desea modificar (archivo .jrxml desde iReport v5.6)
  1. Realizar las modificaciones correspondientes.
  1. Guardar la plantilla con otro nombre.
  1. Compilarla para generar el archivo .jasper que utiliza el sistema para la impresión de la constancia.
  1. Agregar la plantilla generada en el punto anterior al sistema a través de la operación "Administrar Plantillas". En el nombre del archivo no incluir el PATH. IMPORTANTE: Poner "Si" (valor por defecto) en el combo que indica si se permite asociar esta plantilla a una constancia para solicitud 'manual'. Como ejemplo, se recomienda analizar las constancias ya existentes en la instalación del sistema.

  1. En la operación "Administrar Constancias y Certificados" del sistema, ubicar la Constancia a remplazar y editarla eligiendo la nueva plantilla desarrollada en lugar de la que tiene asociada actualmente. ATENCION: Si la plantilla tiene un Formulario asociado, la nueva plantilla deberá tener como parámetros los que pase el formulario dinámicamente y envía a JASPER para la generación del PDF de la Constancia (lo mismo que lo señalado en el caso anterior).

Para cambiar el logo, hoy existen 3 formas de realizar esto:

1 - Realizar los mismos pasos enumerados anteriormente ("Para cambiar el texto") y elegir la imagen directamente desde la plantilla en lugar de utilizar el logo como parámetro. ATENCION: la imagen debe estar ubicada en un directorio donde apache tenga permisos para acceder.

2 - Agregar el archivo "logo_institucion.jpg" en el directorio: $toba_dir/proyectos/guarani/personalizacion/www/img/ . ATENCION: Realizando esto la imagen sera adaptada al tamaño definido en la plantilla a modificar y ubicada en el lugar definido en la misma.

3 - Modificar el método personalizable: get_path_logo_impresion() de la clase "guarani" en el archivo "$toba_dir/proyectos/guarani/personalizacion/php/nucleo/_lib/guarani.php" indicándole el nombre del archivo que contiene la imagen. Este es el menos recomendado de los 3 puntos porque implica una redefinicion del código del sistema, además de contar con las mismas restricciones especificadas en el punto 2 (el tamaño y ubicación)

Agregar mas datos a un certificado o constancia existente

Las constancias existentes, obtienen los datos a mostrar partir de consultas SQL. Para esto, si se desea obtener algún campo extra a mostrar en el reporte, se debe modificar la consulta editando el archivo .jrxml de la constancia deseada y agregando el campo a incluir en la misma. También se debe agregar como campo (Field) del reporte y luego incluirlo en la sección deseada del mismo. Si el dato que se desea agregar no fuera posible obtenerlo a partir de la consulta SQL, o se desea solicitar su valor al usuario, etc...se debe desarrollar un formulario y asociarlo a la constancia en cuestión. Para esto, ver el "Ver ANEXO A".

IMPORTANTE:

  • Recordar lo planteado al comienzo de esta sección: Si bien la idea de realizar esto es cambiar un certificado provisto por el sistema añadiendo nuevos campos, se recomienda en lugar de realizar los cambios sobre las plantillas enviadas, modificarlas desde el editor (iReport) pero grabarlas con otro nombre (por ej.: Constancia Alumno Regular - UNS) y agregarlas como una nueva plantilla del sistema a través de la opción "Administrar Plantillas". De esta forma se evitan conflictos con futuras versiones y actualizaciones del sistema que incluyan un cambio en las plantillas estándares. De hecho, si se desea, para limpiar el combo al asociar una plantilla a una constancia nueva o existente que utilice la plantilla recién creada en lugar de la original, se puede setear las constancia enviadas por el sistema y modificada por estas nuevas, como no habilitadas para la asociación a constancias que se permiten solicitarlas manualmente.
  • La constancia (plantilla JASPER) recibe como parámetros fijos siempre el logo (path) y el nro. de solicitud (registro de la tabla sga_constancias_solicitud). La idea seria realizar una consulta (o modificar la existente) obteniendo los datos a partir de cruzar las tablas pertinentes de la BD tomando como base el nro. de solicitud.
  • Una vez realizadas las modificaciones, recordar compilarla para generar el archivo .jasper que utiliza el sistema para la impresión de la constancia.

ANEXO A: Desarrollar un Formulario para agregar/validar campos a una constancia

Aquí se detallaran los pasos a realizar para personalizar un formulario. Como punto de partida, se recomienda analizar las constancias estándar enviadas con el sistema que utilizan un formulario para agregar o validar campos.

  1. Hacer una carpeta en $toba_dir/guarani/personalizacion/php/UXXX/operaciones/constancias/constancias (donde XXX es el código de institución otorgado por el SIU) con el nombre de la constancia a personalizar/agregar. Ej.: Supongamos que se va a desarrollar un formulario para implementar un certificado de que un alumno esta inscripto en una propuesta. En este caso, el directorio donde hospedar los archivos para el desarrollo del mismo seria: $toba_dir/guarani/personalizacion/php/UXXX/operaciones/constancias/constancias/constancia_inscripto_a_propuesta
  1. Crear un archivo PHP conteniendo a la clase que implementa este fromulario que herede de ci_constancia. Por ej.: Continuando con la implementación del certificado de un alumno inscripto a una propuesta, se crearía en el directorio previamente mencionado un archivo de nombre: ci_constancia_inscripto_a_propuesta_UXXX.php y tendría el siguiente contenido:
<?php
/**
 *
 * @package     Constancias y Certificados
 * 
 */
class ci_constancia_inscripto_a_propuesta_UXXX extends ci_constancia 
{
                
}
?>

En principio, se crea el archivo vacío para que herede el comportamiento estándar de la clase ci_constancia. A futuro, se pueden redefinir los métodos de la misma para agregar validaciones o modificar su comportamiento según lo que se necesite para el formulario en cuestión.


EXPLICACION DEL FUNCIONAMIENTO Y METODOS DE LA CLASE CI_CONSTANCIA:

La clase ci_constancia contiene el comportamiento estándar de una constancia proveyendo métodos para el envío automático de datos y validación de campos estándares. A continuación se explicara su funcionamiento y los métodos principales a redefinir para lograr el funcionamiento deseado.

Se analizara la clase dividiéndola en 3 secciones. A saber: datos iniciales, datos generales y métodos trasversales.
En primer lugar, la clase cuenta con una sección destinada a los datos iniciales del componente tanto para la variable que almacena estos valores, como los métodos que operan sobre la misma.

<?php

        // Datos auxiliares
        protected $s__datos_iniciales;

        /**
         * Se ejecuta al inicio de todos los request en donde participa el componente
         */
        function ini()
        {
                $this->s__datos_iniciales = $this->controlador()->get_params_form_dinamico();   
        }

        function set_datos_iniciales($datos)
        {
                $this->s__datos_iniciales = $datos;
        }
?>

La variable s_datos_iniciales, debe contener los datos a pasar en el arranque del componente, en caso de que el componente o los objetos asociados al mismo lo necesiten para configuraciones iniciales (también se puede re-utilizar para contener valores temporales o valores extras de comunicación con el controlador). De hecho, la primer acción que se realiza ante la creación del componente es inicializar esta variable para que cuando se configuren todos los subcomponentes de la misma puedan contar con este arreglo de datos cargado.

En segundo lugar, se analiza la parte mas importante de la clase. La que consiste en los datos generales que se recopilan y utilizan, previa validación, para pasar los campos a la plantilla para el funcionamiento de la misma.

<?php

        // Datos a pasar al controlador correspondiente a los parametros a grabar
        /*
         * El formato del arreglo de datos debe ser:
         *
         *              datos => (      campo => valor, campo => valor, campo => valor  )
         *
         *                      donde 'campo' debe ser un campo valido registrado en la tabla mce_campos
        */ 
        protected $s__datos;
        
        function get_datos()
        {
                return $this->s__datos;
        }

        function validar_datos()
        {
                /*
                 * El formato del arreglo de datos debe ser:
                 *
                 *              datos => (      campo => valor, campo => valor, campo => valor  )
                 *
                 *                      donde 'campo' debe ser un campo valido registrado en la tabla mce_campos
                 */             
                // Valido que los valores dados por el arreglo a grabar sean campos existentes y con valores validos
                foreach ($this->s__datos as $campo => $valor) {
                        campo::validar_campo_valor($campo, $valor);
                }
                
                return true;
        }

        function set_datos($datos)
        {
                /*
                 * El formato del arreglo de datos debe ser:
                 *
                 *              datos => (      campo => valor, campo => valor, campo => valor  )
                 *
                 *                      donde 'campo' debe ser un campo valido registrado en la tabla mce_campos
                 */             
                // Seteo los datos
                $this->s__datos = $datos;
        }

?>

La idea es que en la variable s_datos se almacenen los campos a pasar a la plantilla (en un arreglo con el formato especificado) a través del método set_datos. El método "validar_datos" contiene una implementación estándar de la validación de los campos (definidos en la tabla mce_campos) según su tipo con el valor que contienen. Si se desean agregar mas validaciones sobre estos campos u otras propias del certificado a implementar se debe redefinir el mismo para realizar las acciones deseadas.

Por ultimo, también se incluyen métodos generales como "get_alumno_seleccionado" para obtener el ID del alumno seleccionado para poder trabajar con el mismo y realizar consultas u obtener mas datos del mismo para enviar al formulario.

<?php

        //-----------------------------------------------------------------------------------
        //---- Funciones Auxiliares ---------------------------------------------------------
        //-----------------------------------------------------------------------------------

        /**
         * Obtiene del ci controlador el alumno seleccionado para el cual se está dando de alta 
         * o editando la Solicitud de Constancia.
         *
         */
        function get_alumno_solicitud()
        {
                return $this->controlador()->get_alumno_seleccionado(); 
        }
        
        function limpiar_datos()
        {
                $this->s__datos = array();
                unset($this->s__datos_iniciales);
        }

?>

  1. Desde el editor de Toba abrir el proyecto "guarani".

  1. Crear un CI con el nombre adecuado. Ej: Certificado de Alumno Inscripto a Propuesta
  • Seleccionar como "Subclase - Archivo" el archivo recién creado. Notar que al elegir el archivo, se autocompleta el campo con el nombre de la Subclase. Si esto no sucede, completarlo manualmente.

source:/trunk/img/Ej_Creacion_CI_Constancia_I.jpg

Imagen 1

  1. Asociar el CI recién creado al componente (CI) "Solicitar Constancias y Certificados - ci_edi_solicitud_constancias" - Identificador: 37000548.
  • Para realizar esto, seleccionar el componente, ir a la pestaña "Dependencias" y en la sección "Objeto asociado" agregar el objeto recién creado. IMPORTANTE: El nombre de la dependencia debe ser el ID del componente creado (el mismo que se utiliza cuando se da de alta un formulario). Tipo: "CI". Componente: El recientemente creado (observar que como contiene como prefijo entre corchetes el ID que se debe poner en el campo nombre)

Ej:
source:/trunk/img/Ej_Creacion_CI_Constancia_II.jpg

Imagen 2


source:/trunk/img/Ej_Creacion_CI_Constancia_III.jpg

Imagen 3

  • A partir de aquí se pueden crear y asociar distintos objetos al componente creado (como por ejemplo un formulario para recopilar mas datos a enviar para luego enviar a la plantilla o un cuadro para mostrar determinados datos y seleccionarlos - Ver la Constancia de Examen). Si se realiza esto, recordar poner el código dentro de la carpeta creada previamente, de forma tal que un mismo componente y los subcomponentes asociados tengan todos los archivos dentro de un mismo directorio.
  1. En el caso de que se haya agregado algún componente para recolectar datos y estos se envíen a la plantilla para ser utilizados en la impresión (almacenados en la variable s_ _datos de la clase ci_constancia con el formato especificado, que se pasa automáticamente a la plantilla) se deben dar de alta en la tabla mce_campos, indicando los siguientes campos:
    • campo: el nombre del campo que se asignara el valor internamente y sera pasado como parametro con este mismo nombre a la plantilla (recordar declarar el parámetro en la plantilla JASPER para ser tomado como entrada)
    • etiqueta y descripcion: strings que describen el campo en cuestión
    • tipo_de_dato: Ver valores posibles en par_tipo_dato
    • longitud: Tamaño del campo
    • cant_decimales: En el caso de que el campo sea entero
  1. Modificar la plantilla JASPER agregando como parámetros los campos especificados en el punto anterior y hacer las modificaciones correspondientes para utilizarlos. Recordar que la constancia (plantilla JASPER) recibe como parámetros fijos siempre el logo (path) y el nro. de solicitud (registro de la tabla sga_constancias_solicitud). Estos datos deben estar como parametros, ademas de los que se desea agregar en la plantilla JASPER.
  1. Dar de alta el formulario en la opción "Administrar formularios". Para esto, además del campo nombre, completar el campo Objeto ID: con el ID asignado por Toba al componente recién desarrollado y que se hizo referencia previamente. Esto es para que se cargue dinámicamente el formulario cuando se solicita la constancia que lo utiliza. Si este dato se carga erróneamente, provocara un error en el sistema cuando se solicite la constancia.




<< volver