SIU-Guarani/Version3.13.0/personalizaciones/personalizaciones gestion
Convenciones sugeridas para personalizar
Requisitos básicos
- Haber realizado los cursos de Toba brindados por el SIU (al menos el de Nivel Inicial) o contar con experiencia en proyectos Toba
- Tener un usuario SVN y la carpeta creada por el SIU en su repositorio para trabajar con personalizaciones en Guaraní
- Contar con un ID de desarrollador brindado por el SIU
- Haber iniciado el esquema de personalizaciones
- 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
Bases de datos
Como es sabido, SIU-Guaraní funciona con dos bases de datos, en realidad en Postgres con una BD y dos schemas, pero se habla de BDs como concepto clásico:
- BD de negocio: almacena toda la información con la que se trabaja en el sistema (alumnos, propuestas, etc..)
- BD de Toba: 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
Convenciones de nombres y carpetas
La idea de fondo respecto a las personalizaciones en SIU-Guaraní es similar al de Autogestión: todo lo que se personalice debe ubicarse dentro de la carpeta <path proyecto Guaraní>/personalizacion, y sólo se deberá agregar allí lo que se quiera personalizar, que tendrá prevalencia por sobre el comportamiento estándar del sistema.
Nota: se debe reemplazar <path proyecto Guaraní> por el path donde está instalado el proyecto SIU-Guaraní Gestión.
Clases
Las personalizaciones a nivel de código se logran utilizando la herencia soportada por PHP.
La idea es extender 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.
Para generar clases propias:
- 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.
- 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 utilizadas por Guarani para definir el comportamiento de objetos, que a la vez heredan de clases proporcionadas por el framework Toba.
- Se pide ésto por dos motivos:
- Para que el objeto obtenga un comportamiento por defecto, permitiendo redefinir el metodo 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_..." específica.
- 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...
- 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 utilizadas por Guarani para definir el comportamiento de objetos, que a la vez heredan de clases proporcionadas por el framework Toba.
Componentes de Toba - Metadatos
Lo que complica la personalización en el sistema de 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 base de datos de Toba, se deben modificar los mismos para poder utilizar los nuevos archivos PHP generados o para cambiar sus propiedades básicas (título, tamaño, etc...). Para tratar este problema, el framework propone una solución dada por un nuevo conjunto de comandos que clonan la base de metadatos (BD Toba) del sistema y luego obtienen las diferencias entre los metadatos modificados 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:
Recomendaciones sobre los componentes
- 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). Se recomienda anexar el sufijo explicitado para identificarlo fácilmente o tener alguna referencia más ante algún pedido de soporte. Aunque desde ya, no es obligatorio realizar ésto.
- Subclase: Debe vincularse con las clases generadas en las sección de Clases
- Carpeta: Ubicar al componente en alguna carpeta relacionada a los conceptos que se quieren personalizar. Recordar que esta ubicación, es la que luego se otorgará en el Menú del sistema.
- Punto de Montaje: se debe fijar el 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.
Funcionamiento general del esquema de personalizaciones
Iniciar las personalizaciones
Al iniciar las personalizaciones mediante:
Exportar los metadatos nuevos
Una vez que se ha finalizado con la implementación de la personalización, y se ha testeado el correcto funcionamiento de la misma, se deben descargar los cambios realizados a los componentes en la BD Toba al sistema de archivos para resguardarlos y versionarlos en el repositorio, se debe usar el comando:
que exporta todos los cambios realizados en los metadatos a <path proyecto Guaraní>/guarani/personalizacion/metadatos.
Desactivar el esquema de personalizaciones
Si por alguna razón se desea desactivar el esquema de personalizaciones para dejar de utilizar el mismo y volver a los metadatos originales del proyecto enviado por el SIU, se ejecuta el comando:
Este comando le indica al sistema que se debe volver a utilizar el esquema original.
Reactivar el esquema de personalizaciones
Si luego de desactivado el esquema de personalizaciones, se desea volver a trabajar con el mismo, se debe volver a ejecutar el comando:
Este comando cambia el archivo 'bases.ini' (<path proyecto Guaraní>/lib/toba/instalacion/bases.ini) para poder trabajar con las personalizaciones.
Para incorporar luego las personalizaciones existentes se debe ejecutar el comando:
Regenerar el autoload
Una vez que se realizó la exportación de los metadatos modificados, se deben incorporar las clases recientemente generadas en el archivo <path proyecto Guaraní>/personalizacion/php/guarani_pers_autoload.php para que se puedan acceder desde otras clases si fuera necesario.
Para esto, ejecutar el comando:
Análisis de conflictos
Existe un comando que permite analizar los posibles conflictos entre los metadatos existentes entre la BD de 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. El comando es:
Puede ser ejecutado previo al comando
