Diferencia entre revisiones de «SIU-Guarani/Version3.11.0/personalizaciones/personalizaciones gestion»

De SIU
Saltar a: navegación, buscar
(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...»)
 
(→‎Exportar los metadatos nuevos)
 
(No se muestran 46 ediciones intermedias de 2 usuarios)
Línea 1: Línea 1:
−
== Ejemplo Básico de personalización de un reporte en SIU-Guarani 3 ==
+
<span style="float: right; margin: 0 0 15px 15px;">{{TOClimit|4}}</span>
 +
== Convenciones sugeridas para personalizar ==
  
−
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'''.<br>
+
=== 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
  
−
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
+
=== 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
  
−
Antes de comenzar, unos párrafos sobre el funcionamiento general de personalizaciones en SIU-Guarani3. <br>
+
=== Convenciones de nombres y carpetas ===
−
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
+
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 <tt><path proyecto Guaraní>/personalizacion</tt>, y sólo se deberá agregar allí lo que se quiera personalizar, que tendrá prevalencia por sobre el comportamiento estándar del sistema.
 +
<br>
 +
'''Nota:''' se debe reemplazar <path proyecto Guaraní> por el path donde está instalado el proyecto SIU-Guaraní Gestión.
  
−
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.<br>
+
==== Clases ====
−
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.
+
Las personalizaciones a nivel de código se logran utilizando la '''herencia soportada por PHP'''.<br>
−
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: <br>
+
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.
  
−
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''").
+
Para generar clases propias:
 +
* Generar la estructura de directorios en '''<path proyecto Guaraní>/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 '''<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...
  
−
'''''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''".
+
==== 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:
 +
<source lang="php" enclose="div">
 +
guarani esquema_pers
 +
</source>
 +
===== 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 [[SIU-Guarani/Version3.11.0/personalizaciones/convenciones_sugeridas#Clases_nuevas_-_C.C3.B3digo|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.
  
−
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.
+
=== Funcionamiento general del esquema de personalizaciones ===
 +
==== Iniciar las personalizaciones ====
 +
Al iniciar las personalizaciones mediante:
 +
<source lang="php" enclose="div">
 +
guarani esquema_pers iniciar
 +
</source>
  
 +
==== Exportar los metadatos nuevos ====
 +
Para pasar las personalizaciones a una nueva versión, el concentrador 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:
 +
<source lang="php" enclose="div">
 +
guarani esquema_pers exportar
 +
</source>
 +
que exporta todos los cambios realizados en los metadatos a <tt><path proyecto Guaraní>/guarani/personalizacion/metadatos</tt>.
  
−
Ver también: [[NotasTecnicas/trabajodiariopersonal| Trabajo Diario con Personalizaciones ]]
+
==== 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:
−
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.<br>
 
−
 
 
−
=== 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:<br>
 
−
 
 
−
==== 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).<br>
 
−
 
 
−
'''RECOMENDACIONES:'''<br>
 
−
 
 
−
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...).<br>
 
−
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'''". <br>
 
−
                                    Donde '''<Tipo_Componente>''' representa el tipo del componente actual. Ej '''ci''','''form''','''cuadro''','''filtro''', etc...<br>
 
−
                                    Donde '''<Nombre_Representativo>''' especifica un nombre acorde a la operacion/comportamiento en cuestión. Ej '''reporte_actas''','''reporte_alumnos_aprobados''','''alta_tramites''', etc...<br>
 
−
                                    Donde '''<Anexo_institucion>''' = ''XXX'' donde ''XXX'' representa el nodo de la insittución otorgado por el SIU como lo especificado previamente.<br>
 
−
      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:
 
 
<source lang="php" enclose="div">
 
<source lang="php" enclose="div">
−
#php
+
guarani esquema_pers desactivar
−
<?php
 
−
class ci_reporte_gastos_U802 extends guarani_pers_ci
 
−
{
 
−
 
 
−
protected $s__datos;
 
−
 
 
−
function get_datos()
 
−
{
 
−
return $this->s__datos;
 
−
}
 
−
 
 
−
}
 
−
?>
 
 
</source>
 
</source>
 +
Este comando le indica al sistema que se debe volver a utilizar el esquema original.
  
−
 
+
==== Reactivar el esquema de personalizaciones ====
−
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...
+
Si luego de desactivado el esquema de personalizaciones, se desea volver a trabajar con el mismo, se debe volver a ejecutar el comando:
−
 
 
−
     
 
−
=== 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:<br>
 
−
*'''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:<br>
 
−
*'''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:
 
 
<source lang="php" enclose="div">
 
<source lang="php" enclose="div">
−
#php
+
guarani esquema_pers iniciar
−
<?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);
 
−
  }
 
−
 
 
−
}
 
−
?>
 
 
</source>
 
</source>
−
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.
+
Este comando cambia el archivo 'bases.ini' (<tt><path proyecto Guaraní>/lib/toba/instalacion/bases.ini</tt>) para poder trabajar con las personalizaciones.<br>
−
 
+
Para incorporar luego las personalizaciones existentes se debe ejecutar el comando:  
−
==== 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:
 
 
<source lang="php" enclose="div">
 
<source lang="php" enclose="div">
−
  toba::consulta_php('co_XXXXXXXX')
+
guarani esquema_pers importar
 
</source>
 
</source>
  
−
En este caso, se debe redefinir la clase de consulta "''co_certificados''" de la siguiente forma:
+
==== 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 <tt><path proyecto Guaraní>/personalizacion/php/guarani_pers_autoload.php</tt> para que se puedan acceder desde otras clases si fuera necesario.<br>
−
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:<br>
+
Para esto, ejecutar el comando:
−
*'''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:
 
 
<source lang="php" enclose="div">
 
<source lang="php" enclose="div">
−
#php
+
guarani pers_autoload
−
<?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);
 
−
  }
 
−
 
 
−
}
 
−
?>
 
 
</source>
 
</source>
−
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 ===
+
==== Análisis de conflictos ====
−
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:
+
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: <tt>conflictos.log</tt> 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:
 
<source lang="php" enclose="div">
 
<source lang="php" enclose="div">
−
guarani esquema_pers exportar
+
guarani esquema_pers conflictos
 
</source>
 
</source>
−
 
+
Puede ser ejecutado previo al comando  
−
=== 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: 
 
 
<source lang="php" enclose="div">
 
<source lang="php" enclose="div">
−
guarani pers_autoload
+
guarani esquema_pers importar
 
</source>
 
</source>

Revisión actual del 21:14 12 abr 2019

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

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:

guarani esquema_pers
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:

guarani esquema_pers iniciar

Exportar los metadatos nuevos

Para pasar las personalizaciones a una nueva versión, el concentrador 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:

guarani esquema_pers exportar

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:

guarani esquema_pers desactivar

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:

guarani esquema_pers iniciar

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:

guarani esquema_pers importar

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:

guarani pers_autoload

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:

guarani esquema_pers conflictos

Puede ser ejecutado previo al comando

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