SIU-Guarani/Version3.13.0/personalizaciones/personalizacion chulupi

Esquema de personalización del Framework Chulupí

El motor de personalización de Chulupí se apoya fuertemente sobre el sistema de archivos y SVN. La idea principal es mantener separado el árbol de código del SIU del de las instituciones que desean cambiarlo; de esta manera, en subsiguientes entregas de código desde el SIU los cambios se pueden reaplicar.

A lo largo de la explicación se usará <path proyecto 3w> para referirse al path donde está instalado el proyecto SIU-Guaraní 3w.

Mecanismo

Los proyectos basados en Chulupí organizan su código de la siguiente manera:

├── bin
├── instalacion
└── src
    ├── pers
    │   ├── ejemplo01
    │   └── ejemplo02
    └── siu

La carpeta src está dividida en dos:

• siu que almacena el código provisto por nosotros
• pers que guarda el código de las instituciones. A la vez, esta tiene un subdirectorio por grupo de personalizaciones. Esto es útil, por ejemplo, para mantener distintas personalizaciones para distintas facultades (logos, colores, etc), con una misma instalación.

Para modificar un archivo en particular se recrea el árbol de directorios del archivo en siu en la carpeta de la personalización.
Es muy importante sólo copiar los archivos que se quieren modificar y no otros. Mientras más archivos se copien mayor el acoplamiento y mayor el potencial de conflictos en el cambio de versión.
Ejemplo: supongamos que queremos modificar el archivo <path proyecto 3w>/src/siu/www/css/preinscripcion.css en la personalización ejemplo01. El árbol de directorios quedaría de la siguiente manera:

└── src
    ├── pers
    │   ├── ejemplo01
    │   │   └── www
    │   │       └── css
    │   │           └── preinscripcion.css
    │   └── ejemplo02
    └── siu
        └── www
            └── css
                └── preinscripcion.css

Activando una personalización en particular

Para activar una personalización, en el archivo config.php (<path proyecto 3w>/instalacion/config.php) se debe activar las personalizaciones y setear que personalización se desea utilizar:
Ejemplo Activación

#php
<?php
    ...
    ...
    array(
           ....
           'usar_personalizaciones' => true,
         ),
    ...
    ...
?>

Elección de personalización 'ejemplo01':

#php
<?php
    ...
    ...
    array(
        'des01' =>
                array(
                ...
                'personalizacion' => 'ejemplo01',
                ...
                ),
          ),

    ...
    ...

?>

Activando una personalización genérica común a toda la institución

A veces las universidades necesitan tener una o varias personalizaciones genéricas que sean comunes a toda la institución o a varias facultades, y varias personalizaciones especificas para cada facultad. Veamos el siguiente ejemplo:

├── bin
├── instalacion
└── src
    ├── pers
    │   ├── pers_institucion
    │   ├── pers_facultad_economicas
    │   └── pers_facultad_exactas
    └── siu

Como se puede ver tenemos la personalización pers_institucion que es común a toda la institución, pers_facultad_economicas y pers_facultad_exactas que son las personalizaciones especificas para la facultad de económicas y de ciencias exactas respectivamente.

Para activar una personalización, en el archivo config.php (<path proyecto 3w>/instalacion/config.php) se debe activar las personalizaciones y setear qué personalización se desea utilizar:

Ejemplo Activación

#php
<?php
    ...
    ...
    array(
           ....
           'usar_personalizaciones' => true,
         ),
    ...
    ...
?>

Elección de personalización 'pers_facultad_economicas':

#php
<?php
    ...
    ...
    array(
        'des01' =>
                array(
                ...
                'personalizacion' => array('pers_institucion', 'pers_facultad_economicas'),
                ...
                ),
          ),

    ...
    ...

?>

La configuración presentada arriba es una configuración en cascada, la personalización pers_institucion sobrescribirá al core (código que proporciona el SIU), por ultimo la personalización pers_facultad_economicas sobrescribirá a la personalización pers_institucion. Cabe destacar que las personalizaciones en cascada no solamente pueden ser de dos niveles como se muestra arriba, sino que pueden ser de N niveles.

Modificando distintos tipos de archivo

En el árbol de código del SIU hay diferentes tipos de archivos; php, js, css y twig. Dependiendo de su tipo la personalización se hace de una manera particular.

Clases php

Para modificar una clase php se debe crear el archivo en el directorio de la personalización. Esta clase debe pertenecer al namespace de la personalización y debe extender de la clase original.

Ejemplo: supongamos que queremos modificar el archivo <path proyecto 3w>/src/siu/extension_kernel/login.php en la personalización ejemplo01 para cambiar la forma de logueo del usuario. Esto se realiza redefiniendo el método autenticar.

• Crear el archivo. Luego de crear el archivo la estructura de directorios queda de la siguiente manera

  └── src
      ├── pers
      │   ├── ejemplo01
      │   │   └── extension_kernel
      │   │       └── login.php
      │   └── ejemplo02
      └── siu
          └── extension_kernel
              └── login.php

• Escribir el código que sobreescribe el comportamiento. En este paso hay que tener en cuenta dos cosas: correctamente modificar el namespace y asegurarse que la clase extienda de la original

  #php
  <?php
  namespace ejemplo01\extension_kernel;
  use siu\errores\error_guarani_login;
  
  class login extends \siu\extension_kernel\login
  {
      function autenticar($id, $clave)
      {
          $parametros = array('usuario' => $id, 'clave' => $clave);
          // se invoca una función del modelo para chequear la validez de la clave
          $id_usuario = catalogo::consultar('persona', 'autenticar', $parametros);
          if (empty($id_usuario)) {
              throw new error_guarani_login('-1');
          }
          return $id_usuario;
      }
  }
  
  ?>

Archivo de mensajes (<path proyecto 3w>/src/siu/mensajes/mensajes.es.php)

Para modificar el archivo de mensajes, como se ha expresado anteriormente, debe recrearse la estructura donde se encuentra el archivo, dentro de la sección correspondiente a personalizaciones.

└── src
    ├── pers
    │   ├── ejemplo01
    │   │   └── mensajes
    │   │       └── mensajes.es.php
    │   └── ejemplo02
    └── siu
        └── mensajes
            └── mensajes.es.php

No se debe copiar el archivo <path proyecto 3w>/src/siu/mensajes/mensajes.es.php entero, sino simplemente se debe copiar el mensaje que se desea cambiar, o bien agregar mensajes nuevos; esto se debe a que el archivo de mensajes personalizado no sobreescribe el archivo original sino solamente aquellos mensajes que fueron modificados.

Ejemplo: se desea modificar el mensaje de bienvenida al sitio y agregar un nuevo mensaje.

El archivo provisto por el SIU contiene el siguiente código:

<?php
return array(
        ...
        'header.bienvenido' => 'Bienvenido',
        ...
        ...
        );

Se modifica solo el mensaje correspondiente a header.bienvenido. Para agregar un mensaje nuevo, se procede de igual manera, añadiendo un elemento al array con una clave que no exista, y el mensaje correspondiente.

<?php
return array(
        'header.bienvenido' => 'Bienvenido al Sitio',
        'nombre_clave_nueva'=> 'mensaje nuevo'
        );

Archivos css

Para modificar archivos css se utiliza el concepto de cascada css. Cuando se personaliza un css el sistema incluye el css del SIU y después incluye el css personalizado. De esta manera se logra pisar el css original.

Ejemplo: supongamos que queremos modificar el archivo <path proyecto 3w>/src/siu/www/css/preinscripcion.css. El árbol de directorios quedaría de la siguiente manera:

└── src
    ├── pers
    │   ├── ejemplo01
    │   │   └── www
    │   │       └── css
    │   │           └── preinscripcion.css
    │   └── ejemplo02
    └── siu
        └── www
            └── css
                └── preinscripcion.css

Si el archivo provisto por el SIU tenía el siguiente código:

#css
.label-obligatorio {
        font-style: italic;
}
...

podemos cambiar el comportamiento simplemente agregando esta clase a nuestro archivo con el nuevo comportamiento:

#css
.label-obligatorio {
        font-style: none;
        font-weight: bold;
}

Archivos js y twig

Para modificar archivos js y twig, debe copiarse el archivo completo en el directorio correspondiente a la personalización, y allí modificar lo que se desea.

Ejemplo: Se quiere modificar el formato en que se muestra el título del inicio de alumno.

Se replica la estructura del directorio en la sección correspondiente a personalizaciones. Se copia el template.twig completo en dicho directorio.

└── src
    ├── pers
    │   ├── ejemplo01
    │   │   └── operaciones
    │   │       └── inicio_alumno
    │   │           └── template.twig
    │   └── ejemplo02
    └── siu
        └── operaciones
            └── inicio_alumno
                └── ...
                └── template.twig
                └── ...

Dentro del template se modifica lo que se desea, por ejemplo, el formato del título:

...
...
{% block titulo_operacion %}<h2>{{"header.bienvenido"|trans|capitalize}} {{ persona.nombre }} </h2>{% endblock %}
...
...

Ejemplo: se desea agrega en el inicio del alumno un botón que oculte el link a 'Lista de Encuestas Pendientes' Para ello debe modificarse, por un lado el twig (para agregar el botón), y por otro lado, el js (para agregarle un comportamiento a dicho botón). Los archivos a modificar en este ejemplo serán:

• inicio_alumno/lista_carreras/default.twig
• inicio_alumno/lista_carreras/pagelet_lista_carreras.js

El primer paso es replicar la estructura del directorio.

└── src
    ├── pers
    │   ├── ejemplo01
    │   │   └── operaciones
    │   │       └── inicio_alumno
    │   │           └── lista_carreras
    │         │             ├── default.twig
    │         │             └── pagelet_lista_carreras.js
    │   └── ejemplo02
    └── siu
        └── operaciones
            └── inicio_alumno
                ├── lista_carreras
                │    ├── default.twig  
                │    └── pagelet_lista_carreras.js
                └── ...

Primero se agrega un botón en el twig, y luego se define el comportamiento para el mismo en el js:

ejemplo01/inicio_alumno/lista_carreras/default.twig

{% extends "kernel/pagelet.twig" %}
{% block contenido %}
....
        <button class="btn btn-primary" id="boton">Ocultar Encuestas</button>

{% endblock %}

ejemplo01/inicio_alumno/lista_carreras/pagelet_lista_carreras.js

kernel.renderer.registrar_pagelet('lista_carreras', function(info) {
    var id = '#' + info.id;

        return {
        onload: function() {
                       
                        $(id + ' #boton').on('click', function () {                            
                                $('#lista_encuestas_pendientes').toggle();
                        });            
        }
    }
})

Archivos de imagenes jpg, png, etc..

Para modificar una imagen, por ejemplo el logo del encabezado de la aplicación, simplemente se agrega la nueva imagen con el mismo nombre de la imagen que queremos reemplazar en el directorio de personalización

Ejemplo: supongamos que queremos modificar el logo <path proyecto 3w>/src/siu/www/img/logo-transparente.png. El árbol de directorios quedaría de la siguiente manera:

└── src
    ├── pers
    │   ├── ejemplo01
    │   │   └── www
    │   │       └── img
    │   │           └── logo-transparente.png
    │   └── ejemplo02
    └── siu
        └── www
            └── img
                └── logo-transparente.png

Para efectivizar la subida de cambios al repositorio, se recomienda incluir un mensaje de log acorde a las personalizaciones subidas, que sirvan a otros miembros del equipo para identificar el conjunto de archivos que descargaran del repositorio con este cambio. Ejecutar en src/pers los siguientes comandos:

 svn add <Nodo uunn>
 svn commit -m "Personalizaciones <Nodo uunn> 3.X.0: Personalización XXXXX"

Modificando el Modelo

Por favor siga el siguiente link para ver las Personalizaciones del modelo

Agregando una librería externa vía Composer

Para agregar una librería externa vía Composer de la cual depende nuestro proyecto, disponemos del archivo src/pers/composer.json. En el mismo se puede agregar una dependencia como sigue:

{
  "require": {
    "nesbot/carbon": "1.22.1"
  }
}

Para mas información ver la documentación de Composer. Esto lo que hará es instalar la librería carbon del vendor nesbot en la versión 1.22.1. Una vez agregada la o las librerías externas deseadas correr el siguiente comando en el directorio raíz del proyecto para proceder a su respectiva instalación:

composer update