SIU-Guarani/Version3.11.0/personalizaciones/personalizaciones gestion

De SIU
Revisión del 13:06 23 sep 2015 de Mchilczenko (discusión | contribuciones) (Página creada con «== Ejemplo Básico de personalización de un reporte en SIU-Guarani 3 == Dado que para personalizar el sistema, se debe trabajar con el '''Editor Toba''' modificando o ag...»)
(dif) ← Revisión anterior | Revisión actual (dif) | Revisión siguiente → (dif)
Saltar a: navegación, buscar

Ejemplo Básico de personalización de un reporte en SIU-Guarani 3

Dado que para personalizar el sistema, se debe trabajar con el Editor Toba modificando o agregando objetos (que componen las operaciones del sistema) es estrictamente necesario contar con experiencia en proyectos Toba, o en su defecto, haber realizado el curso de "Toba - Nivel Inicial" dictado por el SIU.

Como SIU-Guarani3 es un proyecto Toba, también se recomienda leer la documentación existente sobre personalizaciones en proyectos Toba en general, disponible en: http://toba.siu.edu.ar/trac/toba/wiki/Referencia/Personalizaciones

Antes de comenzar, unos párrafos sobre el funcionamiento general de personalizaciones en SIU-Guarani3.
Como es sabido, SIU-Guarani3 funciona con dos BDs (En realidad, en Postgres con una BD y dos schemas, pero se habla de BDs como concepto clásico). Una BD de negocios, donde se almacena toda la información con la que se trabaja en el sistema (Alumnos, propuestas, etc..) y otra BD de Toba. Esta ultima es la que guarda las configuraciones de todos los objetos que componen las operaciones del sistema. Básicamente, los objetos creados en el Editor Toba y todas las propiedades de los mismos, además de configuraciones generales del sistema. El sistema entonces, genera las operaciones a partir del código del framework y las configuraciones antes mencionadas, y define el comportamiento de estos objetos a partir del código del proyecto. Ver la siguiente diapositiva que representa lo explicado: https://docs.google.com/presentation/d/1o-LXKCZ92F1ZqoKi0qpnM11ouAx8WmxSLdBk0pnEji4/edit?usp=sharing

Ahora bien, la idea con respecto a las personalizaciones en SIU-Guarani3 es que tengan un funcionamiento similar al definido para SIU-Guarani3w2. Es decir, que todo lo que el usuario personalice se encuentre dentro de la carpeta "/guarani/personalizaciones", y que solo se agregue lo que se quiera personalizar sobrescribiendo el funcionamiento general del sistema automática e instantáneamente. A nivel de código, esto se logra utilizando la herencia soportada por PHP. La idea es heredar de los componentes ya definidos para la operación que se quiera personalizar (o de los componentes básicos si es una operación nueva) y redefinir los métodos adecuados para lograr el comportamiento que se desee aplicar.
Lo que complica la personalización en el sistema de Gestión Guaraní, a diferencia del web, son los metadatos. Dado que como mencionamos previamente, la configuración de los objetos que componen las operaciones del sistema se almacenan en la BD Toba, se deben modificar los mismos para poder utilizar los nuevos archivos PHP generados o para cambiar sus propiedades básicas (Titulo, tamaño, etc...). Para tratar este problema, el framework propone una solución dada por un nuevo conjunto de comandos que clonan la BD de metadatos (BD Toba) del sistema y luego obtienen las diferencias entre los metadatos tocados y originales exportando los mismos al sistema de archivos para poder regenerarlos posteriormente y compartirlo con el resto de los miembros del equipo. El conjunto de comandos que se mencionan en el párrafo anterior, son los de la familia de "guarani esquema_pers". El funcionamiento en general del esquema de personalizaciones puede describirse de la siguiente forma:

Al iniciar las personalizaciones mediante guarani esquema_pers iniciar, se clona la BD de Toba del sistema (además, cambia el archivo "bases.ini" para apuntar al nuevo esquema clonado. Por defecto: "toba_guarani_pers"). Una vez clonada, se modifican todos los metadatos que se desee para realizar las personalizaciones. Notese que estos cambios se efectúan sobre el esquema clonado y no el original. Ahora resta descargar los cambios realizados a los componentes en la BD Toba al sistema de archivos para resguardarlos y versionarlos en el repositorio. Esto se logra con el comando guarani esquema_pers exportar, que exporta todos los cambios realizados en los metadatos a "/guarani/personalizacion/metadatos". Si por alguna razón se desea desactivar el esquema de personalziaciones para dejar de utilizar el mismo y volver a los metadaatos originales del proyecto enviado por el SIU, se ejecuta el comando "guarani esquema_pers desactivar". Este comando le indica al sistema que se debe volver a utilizar el esquema original y no el clonado previamente con los metadatos modificados (cambia el archivo "bases.ini" y vuelve a apuntar al esquema original. Por defecto: "toba_guarani").

IMPORTANTE: Si luego de desactivado el esquema de personalizaciones, se desea volver a trabajar con el mismo, se debe volver a ejecutar el comando "guarani esquema_pers iniciar" que clona la BD de metadatos originales y luego importar los cambios propios o adquiridos del repositorio almacenados en "/guarani/personalizacion/metadatos". Este comando no inicia el esquema aplicando automaticamente las personalizaciones existentes. Solamente clona la BD toba y cambia el archivo "bases.ini" para poder trabajar con el mismo. Para incorporar luego las personalziaciones existentes se debe ejecutar el comando: "guarani esquema_pers importar".

Un párrafo final para el comando "guarani esquema_pers conflictos". Este comando puede ser ejecutado previo al comando "guarani esquema_pers importar" para analizar los posibles conflictos entre los metadatos existentes entre la BD Toba actual y las personalizaciones a importar. Funciona como una simulación del proceso de importación de metadatos de personalizaciones y genera el archivo: "conflictos.log" conteniendo los potenciales conflictos detectados, de forma tal que el usuario pueda analizar los mismos y tomar acciones correctivas para evitar que sucedan.


Ver también: Trabajo Diario con Personalizaciones

Comenzando entonces con el ejemplo planteado, una vez iniciado el esquema de personalizaciones en Guaraní 3, según lo indicado en la documentación de instalación del sistema, se puede proceder con el desarrollo de las mismas.

Requisitos Básicos

  • Tener un usuario SVN y la carpeta creada por el SIU en su repositorio para trabajar con personalizaciones en Guarani3
  • Contar con un ID de desarrollador brindado por el SIU
  • Haber realizado los cursos de TOBA brindados por el SIU (al menos el de Nivel Inicial)
  • Haber iniciado el esquema de personalizaciones

Ante cualquier duda sobre desarrollo en SIU-Toba, consultar la documentación disponible: http://toba.siu.edu.ar/trac/toba/wiki/Referencia


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:

1 - 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: Color(none,red, OBLIGATORIO) fijar como punto de montaje para el item "personalizacion"
  • Modelo Pagina: Pagina SIU-Guarani. La pagina estandar del proyecto que contiene los recursos basicos del mismo. Esto facilita la implementacion 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.

2 - 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: Image(editar.gif), se debe proceder con el clonado del mismo (seleccionando Image(clonar.gif) en la esquina superior derecha) marcando:

  • Anexo nombre: Color(none,red, 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: Color(none,red, OBLIGATORIO) SI. Asignárselo al ítem generado en el paso anterior.

3 - 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.

4 - 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. Esto 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: 

a) Generar la estructura de directorios en "/guarani/personalizacion/php/XXX/operaciones/...", concordante con el orden del menú del sistema o siguiendo modulo-submodulo. Se recomienda mantener el estándar de nombres fijado por el SIU y no generar cualquier estructura o nombre de directorio. Esto es primordial para mantener el orden de las personalizaciones generadas y poder encontrar fácilmente los nuevos archivos creados.  

b) En el Editor Toba seleccionar para el componente:
    • Punto de Montaje: personalizacion. Esto indica que la carpeta base donde ubicar los archivos del componente sera "/guarani/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". 
                                   Donde <Tipo_Componente> representa el tipo del componente actual. Ej ci,form,cuadro,filtro, etc...

                                   Donde <Nombre_Representativo> especifica un nombre acorde a la operacion/comportamiento en cuestión. Ej reporte_actas,reporte_alumnos_aprobados,alta_tramites, etc...

                                   Donde <Anexo_institucion> = XXX donde XXX representa el nodo de la insittución otorgado por el SIU como lo especificado previamente.

      De esta forma, el nombre final del componente quedara 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.
c) 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 uds. pueden (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 "/guarani/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 Guarani 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: El primero para que el objeto obtenga un comportamiento por defecto, permitiendo redefinir el metodo desesado para generar un comportamiento particular. El segundo, 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
<?php
 class ci_reporte_gastos_U802 extends guarani_pers_ci
 {

        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, donde 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 practicamente todos los cambios que esto involucra.

El reporte elegido para mostrar esto, 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:

1 - 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.

2 - 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 personalizacion, 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 "guarani/personalizacion/php/XXX/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. Primero habría que modificar el cuadro para agregarle la columna extra. Segundo, 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. Y tercero, modificar la Clase de Consulta PHP para personalizarla y agregar una nueva que extienda de la existente con la consulta propia que devuelva ademas de los valores que traia el nuevo valor de la columna a agregar que luego sera invocada desde el controlador.

Entonces, se debe hacer:

2.1 - Modificar el cuadro para agregar la nueva columna

Editar el objeto cuadro de esta operación presionando Image(editar.gif). 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 "guarani/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".


2.2 - Modificar el CI

Editar el objeto CI, llamado normalmente igual que la operación, en este caso: Certificados presionando Image(editar.gif). 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 ("guarani/personalizacion/php/XXX/operaciones), que extienda de la original. En este caso entonces, a traves del editor crear la estructura de carpetas y el archivo: UXXX/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 "guarani/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.

2.3 - 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 Image(editar.gif). Realizar los siguientes cambios:

  • Punto de Montaje : "personalizacion".
  • Clase: "co_certificados_XXX"
  • Archivo: La idea es crear una clase dentro de la misma estructura de carpetas que la original pero en otro path ("guarani/personalizacion/php/XXX/nucleo), que extienda de la original. En este caso entonces, a traves del editor crear la estructura de carpetas y el archivo: XXX/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 "guarani/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
<?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($filtro)
   {
        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.

3 - Testeo y Exportación

Una vez que se ha finalizado con la implementación de la personalizacion, y se ha testeado el correcto funcionamiento de la misma, se deben exportar los cambios en los metadatos modificados. Esto se logra con el comando:

 guarani esquema_pers exportar

4 - Regenerar Autoload

Una vez que se realizó la exportación de los metadatos modificados, se deben incorporar las clases recientemente generadas en el archivo "guarani/personalizacion/php/guarani_pers_autoload.php" para que se puedan acceder desde otras clases si fuera necesario. Para esto, ejecutar el comando:

 guarani pers_autoload
Obtenido de «https://documentacion.siu.edu.ar/wiki/index.php?title=SIU-Guarani/Version3.11.0/personalizaciones/personalizaciones_gestion&oldid=2481»