SIU-Guarani/Version3.11.0/personalizaciones/personalizaciones gestion
Sumario
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 negocios: 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
Carpeta de personalizaciones
La idea con respecto a las personalizaciones en SIU-Guaraní es que tengan un funcionamiento similar al definido para SIU-Guaraníw2. 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.
Clases
Las personalizaciones a nivel de código se logran 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.
Para generar clases propias:
- Generar la estructura de directorios en "/guarani/personalizacion/php/XXX/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 "/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 ésto por dos motivos:
- Para que el objeto obtenga un comportamiento por defecto, permitiendo redefinir el metodo desesado 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...
- 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.
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á "/guarani/personalizacion" y que constituye efectivamente un componente personalizado.
Funcionamiento general del esquema de personalizaciones
Iniciar las personalizaciones
Al iniciar las personalizaciones mediante:
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.
Exportar los metadatos nuevos
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:
que exporta todos los cambios realizados en los metadatos a "/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 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").
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:
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 automáticamente las personalizaciones existentes. Solamente clona la BD toba y cambia el archivo "bases.ini" para poder trabajar con el mismo. Para incorporar luego las personalizaciones existentes se debe ejecutar el comando:
Testeo y exportación
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 exportar los cambios en los metadatos modificados. Esto se logra con 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 "guarani/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
