SIU-Guarani/Version3.22.0/personalizaciones/reporte

Personalizar un reporte

Crear un nuevo reporte

Si lo que se desea es generar un nuevo reporte en el sistema, se recomienda "clonar" uno existente, ya generado por el SIU que contenga la misma estructura que el que se desea desarrollar. Básicamente, que sea lo mas parecido posible al reporte deseado. Entonces:

Generar el ítem

Crear el nuevo ítem con el nombre del reporte en la carpeta deseada (correspondiente a la ubicación en el menú del sistema).

RECOMENDACIONES:

Para las propiedades del item creado, considerar lo siguiente:

• Nombre: Anexar " - XXX" (donde XXX es el nodo que le otorgó el SIU a la institución. Si quisieran diferenciar las personalizaciones entre las unidades académicas les podrían agregar -YYY donde YYY sería el código de unidad académica , EJ: uba-fcen). Si bien se fija como estándar que los objetos hijos del ítem generados para este reporte y los archivos asociados a los mismos, contengan el sufijo "_XXX" se recomienda anexar el sufijo explicitado para identificarlo fácilmente o tener alguna referencia mas ante algún pedido de soporte. Aunque desde ya, no es obligatorio realizar esto (Si para los estándares mencionados previamente).
• Carpeta: Ubicarlo en alguna carpeta relacionada a los conceptos involucrados directamente en el reporte. Recordar que esta ubicación, es la que luego se otorgara en el Menú del sistema.
• Punto de Montaje: OBLIGATORIO fijar como punto de montaje para el item "personalizacion"
• Modelo Página: Página SIU-Guarani. La página estandar del proyecto que contiene los recursos basicos del mismo. Ésto facilita la implementación de futuras personalizaciones (si se desea, claro está) a todas las operaciones del sistema.
• Imagen: Proyecto - Reporte.png . El icono estándar que identifica de los reportes en el sistema.

Clonar los componentes

Ubicar el CI (Controlador de negocio) de la operación de la cual se quiera clonar el reporte. Normalmente, tiene el mismo nombre que el Item padre, y es el que contiene todas las pantallas y objetos (cuadros, filtros, etc...) que componen la operación. Una vez seleccionado para edicion: , se debe proceder con el clonado del mismo (seleccionando en la esquina superior derecha) marcando:

• Anexo nombre: OBLIGATORIO "XXX_" (donde XXX corresponde al nodo de la Institución como fue indicado previamente). De esta forma los componentes se crearan con ese prefijo y podrán ser fácilmente identificables. De todas formas, luego habrá que renombrarlos para ponerlo como sufijo en lugar de prefijo como indica el estándar.
• Clonar Dependencias: SI. De esta forma, se clonan todos los subcomponentes del mismo evitando tener que clonar uno a uno mas tarde. En caso que no se desee utilizar en la operación alguno de los componentes hijos, se elimina posteriormente.
• Clonar Subclases: NO. Es preferible generar solo las clases que se utilizaran. Ademas, estas clases contienen metodos que seran heredados por las nuevas generadas por lo que no es necesario copiar los mismos en este paso.
• Asignar a un componente: OBLIGATORIO SI. Asignárselo al ítem generado en el paso anterior.

Modificaciones post-clonado

Luego de clonados los componentes de la operación, se deben editar uno a uno cambiando las propiedades de los mismos según lo deseado (Titulo, ancho de los componentes, pantallas etiquetas, etc...).
Es imprescindible, teniendo en cuenta los pasos realizados anteriormente, acomodar los nombres de los componentes siguiendo los estándares: Especificar como sufijo "_XXX"y no como prefijo de los mismos, dado que Toba nomencla de esa forma los objetos al clonarlos.

Agregando clases propias

Al clonar los componentes de la operación, el comportamiento de los mismos queda definido por las mismas clases (archivos PHP) que las del componente origen clonado. Es normal, querer definir clases propias para modificar el comportamiento original o agregar nuevos comportamientos para el nuevo reporte generado. Ésto también es necesario, en caso que el reporte difiera del original al agregar o eliminar una columna del mismo o simplemente porque se desea mostrar otros datos diferentes al original.

Para generar clases propias que definan el nuevo comportamiento de la operación realizar lo siguiente:

1. Generar la estructura de directorios en <path proyecto Guaraní>/personalizacion/php/operaciones/..., concordante con el orden del menú del sistema o siguiendo módulo-submódulo. Se recomienda mantener el estándar de nombres fijado por el SIU y no generar cualquier estructura o nombre de directorio. Ésto es primordial para mantener el orden de las personalizaciones generadas y poder encontrar fácilmente los nuevos archivos creados.
2. En el Editor Toba seleccionar para el componente:
   • Punto de Montaje: personalizacion, que indica que la carpeta base donde ubicar los archivos del componente será <path proyecto Guaraní>/personalizacion y que constituye efectivamente un componente personalizado.
   • Subclase - Archivo: Dentro de la estructura de carpetas creada en el punto anterior, generar el archivo cuyo nombre tenga la forma: "<Tipo_Componente>_<Nombre_Representativo>_<Anexo_institucion>.php".
     
     • <Tipo_Componente> representa el tipo del componente actual. Ej ci,form,cuadro,filtro, etc...
       
     • <Nombre_Representativo> especifica un nombre acorde a la operacion/comportamiento en cuestión. Ej reporte_actas,reporte_alumnos_aprobados,alta_tramites, etc...
       
     • <Anexo_institucion> = XXX, que representa el nodo de la institución otorgado por el SIU como lo especificado previamente.
       

     De esta forma, el nombre final del componente quedará del tipo: ci_reporte_inscripcion_uba-fcen.php, formulario_datos_uba-fcen.php, cuadro_reporte_inscripcion_uba-fcen.php....

   • Subclase: Nombre de la clase. El mismo que el nombre del archivo.
3. Una vez realizados los pasos anteriores, llega el momento de generar código para definir el comportamiento de la nueva operación. Dado que el código de Guaraní es abierto, por lo que se puede (y de hecho se recomienda) mirar el código de las operaciones ya desarrolladas por el SIU, se deja a criterio de la institución la implementación del mismo teniendo en cuenta las siguientes recomendaciones:
   • La nueva clase generada, dependiendo del tipo de componente en cuestión, debe heredar de una de las clases vacías incluidas en <path proyecto Guaraní>/personalizacion/php/extension_toba/componentes/. Estas clases definen el comportamiento estándar de los objetos. Observar que cada una de ellas heredan de las clases definidas por Guaraní para definir el comportamiento de objetos, que a la vez heredan de las clases estándares proporcionadas por el framework Toba.

     Se pide esto por dos motivos:

     • Para que el objeto obtenga un comportamiento por defecto, permitiendo redefinir el método deseado para generar un comportamiento particular.
     • Permite que si a futuro se desea definir un nuevo comportamiento para todos los objetos de este tipo, el mismo sea definido en la clase "guarani_pers_..." especifica.
   • Observar los métodos heredados de la misma y redefinir solamente los que se desee cambiar el comportamiento. Por ejemplo, los métodos que buscan y asignan datos a un cuadro, los que definen comportamiento de eventos, etc...

   Por ejemplo, una clase propia llamada "ci_reporte_gastos_unca" que redefine el comportamiento de un ci seria la siguiente:

   <?php
    class ci_reporte_gastos_U802 extends ci_reporte
    {
   
           protected $s__datos;
   
           function get_datos()
           {
                   return $this->s__datos;
           }
   
    }
   ?>

Se recomienda leer también la sección siguiente para ver un ejemplo concreto y tener un mayor conocimiento de que código incluir en cada archivo, dónde generar los mismos, etc...

Modificar un reporte existente

Veamos ahora un ejemplo sencillo de modificación de un reporte existente. La idea es tomar un reporte simple y agregar una nueva columna, para demostrar prácticamente todos los cambios que involucra.

El reporte elegido es el "Reporte de Certificados" ubicado en: Propuestas Formativas -> Reportes -> Certificados. Supongamos que se quiere agregar la columna "duracion_en_meses" de la tabla "sga_certificados" que representa la validez en meses del certificado en cuestión. Veamos entonces, los pasos a seguir:

Identificar en el editor Toba la operación a personalizar

Abriendo el Editor Toba para el proyecto "guarani", ubicamos la operación existente a extender. En este caso, expandir la carpeta "Propuestas Fromativas" -> "Reportes" -> "Certificados". Al expandir el ítem de la operación vemos que la misma esta compuesta por un CI (Controlador de Interfaz) y 2 objetos: un filtro y un cuadro. Llega el momento entonces, de analizar los cambios que se quieren implementar, para saber cual de los objetos de la operación hay que redefinir.

Aplicar cambios en objetos correspondientes

La forma tradicional de realizar cambios en los objetos del sistema es: ubicar el objeto a editar, cambiar el "Punto de Montaje" a personalización, editar las propiedades adecuadas del objeto y crear la clase que contendrá el comportamiento deseado dentro de una estructura de directorios similar a la original en la carpeta <path proyecto Guaraní>/personalizacion/php/operaciones que extienda de la clase original que utilizaba el objeto (opcional, en caso de que no se utilice el comportamiento estándar de los objetos de este tipo).

En este caso, tenemos que hacer 3 cambios:

1. Modificar el cuadro para agregarle la columna extra.
2. Modificar el controlador para utilizar una clase propia donde se modifique la consulta a utilizar para usar una nueva que incluya la columna a agregar.
3. Modificar la clase de consulta PHP para personalizarla y agregar una nueva que extienda de la existente con la consulta propia que devuelva además de los valores que traía el nuevo valor de la columna a agregar que luego sera invocada desde el controlador.

Entonces, se debe:

Modificar el cuadro para agregar la nueva columna

Editar el objeto cuadro de esta operación presionando . Realizar los siguientes cambios:

• Punto de Montaje : "personalizacion". Esto debe realizarse siempre para todos los objetos que se personalicen, dado que permite la exportación de los cambios realizados a la carpeta propia "personalizacion". En este caso, esto ya estaba configurado dado que extendía de la clase genérica "guarani_pers_ei_cuadro" que contiene el comportamiento genérico para todos los cuadros del sistema.
• Subclase archivo: En este caso, no se va a personalizar el cuadro, dado que solo se agregara la columna en el objeto y luego se cambiara la consulta desde el CI, por lo que quedara apuntando a la clase previamente mencionada. Sin embargo, tener en cuenta que si se necesita modificar el comportamiento del mismo, se debera crear una nueva clase que extienda de la original en una estructura de directorios similar dentro de <path proyecto Guaraní>/personalizacion.

En la solapa "Columnas", agregar la nueva columna "duracion_en_meses" con los siguientes datos:

• Columna: "duracion_en_meses"
• Titulo: Validez

Ninguna propiedad mas se necesita para este ejemplo, por lo que al final la edición de las propiedades del cuadro, presionar el botón "Guardar".

Modificar el CI

Editar el objeto CI, llamado normalmente igual que la operación, en este caso: Certificados presionando . Realizar los siguientes cambios:

• Punto de Montaje : "personalizacion".
• Subclase archivo: La idea es crear una clase dentro de la misma estructura de carpetas que la original pero en otro path (<path proyecto Guaraní>/personalizacion/php/operaciones), que extienda de la original. En este caso entonces, a traves del editor crear la estructura de carpetas y el archivo: operaciones/propuestas/certificados/ci_rep_certificados_XXX.php (donde XXX es el nodo de la institución otorgado por el SIU). Esta estructura de directorios se creara dentro de <path proyecto Guaraní>/personalizacion/php ya que previamente indicamos el punto de montaje "personalizacion".
• Subclase: El mismo nombre que el archivo: "ci_rep_certificados_XXX"

Una vez realizado esto, presionar el botón "Guardar" para almacenar los cambios realizados y luego abrir el archivo recién creado y dejarlo de la siguiente forma:

#php
<?php
 class ci_rep_certificados_XXX extends ci_rep_certificados
 {

   // Se redefine la funcion que obtiene los datos a traves de una consulta propia
   function get_datos($filtro)
   {
      return toba::consulta_php('co_certificados')->get_listado_validez($filtro);
   }

 }
?>

De esta forma, se redefine solamente el método que traía los datos del cuadro sustituyéndolo por el que obtiene los datos de la nueva consulta que generaremos en el paso siguiente.

Modificar la clase de consulta

Para consultar a la BD de negocios del sistema, SIU-Guarani cuenta con un conjunto de clases (aproximadamente una por modulo-submodulo) definidas en la solapa "Datos" -> "Consultas PHP" del Editor Toba. Las clases de consultas definidas allí, son accesibles a través del framework desde cualquier clase a partir del llamado:

  toba::consulta_php('co_XXXXXXXX')

En este caso, se debe redefinir la clase de consulta "co_certificados" de la siguiente forma:

Ir a la la solapa "Datos" -> "Consultas PHP" del Editor Toba y seleccionar para editar la clase de Consulta "co_certificados" presionando . Realizar los siguientes cambios:

• Punto de Montaje : "personalizacion".
• Clase: "co_certificados_XXX"
• Archivo: La idea es crear una clase dentro del path (<path proyecto Guaraní>/personalizacion/php/nucleo) que extienda de la original. En este caso entonces, a traves del editor crear la estructura de carpetas y el archivo: nucleo/propuestas/certificados/co_certificados_XXX.php (donde XXX es el nodo de institución otorgado por el SIU). Esta estructura de directorios se creara dentro de <path proyecto Guaraní>/personalizacion/php ya que previamente indicamos el punto de montaje "personalizacion".

Una vez realizado esto, presionar el botón "Guardar" para almacenar los cambios realizados y luego abrir el archivo recién creado y dejarlo de la siguiente forma:

<?php
 class co_certificados_XXX extends co_certificados
 {

   // Se agrega el siguiente metodo como una nueva consulta a la BD para traer ademas de los datos basicos, el campo 'duracion_en_meses'
   function get_listado_validez($where)
   {
        if ($where) {
                $where = 'AND ' . $where;
        }
               
        $sql = "SELECT  sga_certificados.certificado,
                        sga_certificados.nombre,
                        sga_certificados.nombre_femenino,
                        sga_certificados_tipos.certificado_tipo as certificado_tipo_codigo,
                        sga_certificados_tipos.descripcion as certificado_tipo,
                        sga_titulos_niveles.descripcion as titulo_nivel,
                        sga_certificados.disciplina,
                        sga_certificados.titulo_araucano,
                        ".guarani_sql::get_case('sga_certificados','estado').",
                        sga_certificados.codigo,
                        sga_g3entidades.entidad,
                        sga_certificados.duracion_en_meses
                FROM    sga_certificados
                        LEFT JOIN sga_titulos_niveles ON sga_certificados.titulo_nivel = sga_titulos_niveles.titulo_nivel
                        LEFT JOIN sga_g3entidades ON sga_certificados.entidad = sga_g3entidades.entidad,
                        sga_certificados_tipos
                WHERE   sga_certificados.certificado_tipo = sga_certificados_tipos.certificado_tipo
                        $where
                ORDER BY        codigo,
                                certificado_tipo,
                                titulo_nivel
        ";
        return guarani_db::consultar($sql);
   }

 }
?>

De esta forma, se redefine solamente el método que traía los datos del cuadro sustituyéndolo por el que obtiene los datos de la nueva consulta que generaremos en el paso siguiente.

Regenerar el autoload

Se deben incorporar las clases recientemente generadas en el archivo <path proyecto Guaraní>/personalizacion/php/guarani_autoload_clases_nuevas.php para que se puedan acceder desde otras clases si fuera necesario. Para esto, ejecutar el comando:

 guarani pers_autoload