Modificaciones a las fuentes

Aunque modificar las fuentes de SIVeL, como con cualquier otro proyecto requiere previo estudio de estas, algunos detalles facilitarán la labor: se emplean estándares de programación; se cuenta con pruebas de regresión (ver la sección de nombre Pruebas de regresión en Capítulo 5) que facilitan la detección de errores que podrían introducirse al modificar las fuentes; se emplean librerías estándares de Pear (resaltamos DB_DataObject_FormBuilder).

Estándares de programación

En cuanto a base de datos se emplea SQL estándar con nomenclatura de tablas en síngular y campo llave único de nombre id. Para las partes en PHP se emplean estándares de PEAR (ver [pearcs]) ampliados con reglas de nomenclatura de silverorange (ver [nomenclaturaphp] y personalización de estándar en herram/estandares.xml). Los estándares de PEAR se verifican con la herramienta phpcs del paquete PHP_CodeSniffer (ver [phpcs]), el cual puede instalarse con:


sudo pear install PHP_CodeSniffer
            
y una vez instalado puede verificarse con:

herram/estandares.sh
			
Los errores quedarán en el archivo /tmp/e

Documentación técnica

Siguiendo el estándar adoptado para PHP, las fuentes incluyen comentarios que permiten generar documentación técnica con la herramienta phpdoc (ver [phpdoc]), la cual típicamente se instala desde la línea de comandos con:


sudo pear install PHPDocumentor
            
Esta herramienta requiere bastante memoria por lo que se sugiere verificar en /var/www/conf/php.inf que memory_limit sea por lo menos 256M. La documentación de SIVeL se genera con:

make tecdoc
		    
El resultado queda en el directorio pdoc o puede consultarse en http://sivel.sf.net/1.1//tec/.

Documentación de usuario

Se emplea DocBook con las facilidades de repasa[1]. Está disponible en formato HTML en http://sivel.sf.net.

Para generarla a partir de fuentes primero configure con:


cd doc
./conf.sh
            
y si cuenta con todas las herramientas necesarias generela con

make
            
Puede consultar más documentación sobre las fuentes y el desarrollo de esta documentación en doc/Leame.txt y doc/Desarrollo.txt

Arquitectura de la Aplicación

Se trata de una aplicación web modular y orientada a objetos cuyos roles se identifican en la sección la sección de nombre Recurso Humano en Capítulo 2. Un esobozo de arquitectura se presenta en la siguiente figura (completamos los diagramas de la sección de nombre Infraestructura Tecnológica en Capítulo 2).

Control de versiones

Las fuentes de la aplicación se mantienen en un repositorio CVS amablemente mantenido por SourceForge y utilizable públicamente en modo de sólo lectura.

Los usuarios anonimos puede extraer fuentes de sólo lectura con:


cvs -z3 -danonymous@sivel.cvs.sourceforge.net:/cvsroot/sivel co -rSIVEL1_1 sivel
                    
Los desarrolladores pueden extraer las fuentes de lectura/escritura como se presenta a continuación (remplace miusuario por su identificación en SourceForge):

cvs -z3 -dmiusuario@sivel.cvs.sourceforge.net:/cvsroot/sivel co -rSIVEL1_1 sivel
                    
o una vez con las fuentes pueden establecerse las variables CVSROOT y CVS_RSH con la utilidad pcvs.sh:

./pcvs.sh
cvs -z3 co sivel
                    

La rama de las versión 1.1 es: "SIVEL1_1". La versión en desarrollo está en la rama "HEAD".

Organización de fuentes

Las extensiones empleadas a lo largo de las fuentes son:

Fuentes de herramientas administrativas y de desarrollo

Para configurar fuentes se emplea conf.sh que proviene del módulo devel/confsh del repositorio CVS de structio (ver http://structio.sf.net). Los archivos relacionados con esta herramienta se instalan/verifican con el archivo de comandos enlaces.sh de esa herramienta y en el momento de este escrito son: herram/comdist.mak, herram/confaux.sh, herram/misc.sh, herram/rtest.sh conf.sh y confv.empty.

En el directorio bin hay algunas herramientas para realizar operaciones administrativas desde el interprete de comandos. Puede ver la descripción de cada una en la sección de nombre Labores administrativas desde el interprete de comandos en Capítulo 4.

El archivo de comandos herram/buscafallas.sh verifica que se sigan algunas prácticas seguras en las fuentes.

Fuentes de pruebas de regresión

Ubicados en directorio sitios/pruebas. Unas se ejecutan desde la línea de comandos, las otras --con extensión .selenio-- se ejecutan con Selenium IDE. Vea detalles en la sección de nombre Pruebas de regresión en Capítulo 5.

Fuentes de SIVeL Básico

Ubicadas en directorio principal y en DataObjects. Los grupos principales de las fuentes PHP son: (1) DB_DataObject_SIVeL.php y DataObjects/*php una clase por cada tabla para modelar un registro; (2) captura_caso.php, buscarGrupo.php, buscarPersona.php, eliminar_caso.php y Pag*php que corresponden a pestañas de la ficha de captura; (3) consulta_web.php, consulta_web_cat.php, consulta_web_correo.php y ResConsulta.php para realizar consultas detallada y web; (4) consolidado.php y ResConsulta.php para generar reportes; (5) tablas_basicas.php, tabla.php, detalle.php para administrar tablas básicas; (6) usyroles.php, detus.php para administrar usuarios; (7) misc.php, misc_caso.php, misc_actualiza.php y opcion.php con funciones auxiliares empleadas a lo largo de las fuentes; (8) importaRelato.php, actualiza.php, completaActos.php, verifica.php que realizan las operaciones del menú Otros; (9) index.php, PresentaMenuPrincipal.php con el menú principal.

Fuentes de Sitios

La posiblidad de hacer instalación multisitio y de crear nuevos módulos (inspirado en Drupal) facilita la separación de las fuentes genéricas de las fuentes personalizadas. De esta forma incluso en algunas personalizaciones profundas podrá actualizar sólo SIVeL genérico.

Cada sitio debe ser un directorio dentro del directorio sitios y debe contar con enlaces por cada forma en la que puede ingresarse al sitio. Por ejemplo si ha configurado Apache para ingresar como http://127.0.0.1/misivel debe tener un enlace al directorio del sitio de nombre 127.0.0.1_MISIVEL.

Fuentes de Módulos

Cada módulo se ubica en un directorio al interior del directorio modulo. Vea más adelante los archivos que componen un módulo.

Interfaz

La interfaz se desarrolló en PHP (ver [php]) empleando diversas librerías de Pear (ver [pear]), entre las que destacamos:

DB_DataObject_FormBuilder

Que permite generar formularios semiautomáticamente a partir de objetos DB_DataObject empleando algún sistema de presentación como HTML_QuickForm (ver [dbdataobjectformbuilder]).

DB_DataObject

Que abstrae una base de datos SQL, identificando tablas con clases y registros con objetos (ver [dbdataobject]).

Se empleo programación orientada a objetos, las clases y su jerarquía pueden verse en la documentación técnica (ver la sección de nombre Documentación técnica)

Base de Datos

En cuanto a base de datos la estructura en SQL (ver [sqlpost]) de SIVeL genérico está en el archivo estructura.sql y los datos iniciales en archivos con nombres de la forma datos-*.sql. A continuación se incluye un grafo extaido de estructura.sql y generado con GraphViz (ver [graphviz]).

Separación de fuentes genéricas de las personalizadas

Para hacer una personalización se sugiere iniciar un nuevo sitio, digamos sitios/sivelper, que puede crear con


cd sitios
./nuevo.sh sivelper
		    
Este archivo de comandos creará el directorio con los archivos que requiere para comenzar y generará una nueva base de datos sivelper.

Por su parte un nuevo módulo se puede iniciar por ejemplo en modulos/nuevomod

La estructura de un sitio y de un módulo es la misma, ambos tienen algunos archivos que son puntos de unión con el SIVeL genérico:

sitios/sivelper/estructura.sql

Donde declara en SQL las nuevas tablas, secuencias y elementos estructurales de la base de datos. Este archivo será ejecutado en nuevas instalaciones de su personalización cuando se cree la base de datos.

sitios/sivelper/datos.sql

Donde inserta en SQL datos iniciales para las tablas de SIVeL y su personalización. Se ejecuta durante la creación de la base de datos, después de que se ha ejecutado sitios/sivelper/estructura.sql. En este archivo también debe incluir las actualizaciones de sitios/sivelper/actualiza.php.

sitios/sivelper/prepara-indices.sql

Que actualiza índices definidos en estructura.sql a los máximos valores usados en las tablas o al mínimo de datos personalizados en casos de tablas básicas.

sitios/sivelper/actualiza.php

Este se ejecutará cuando desde la interfaz web el usuario solicite actualizar, por lo que recomendamos que cree las mismas bases de datos de sitios/estructura.sql e incluya los mismos datos de sitios/datos.sql. A medida que desarrolle su personalización/módulo podrá realizar cambios a la base de datos añadiendolos como actualizaciones a este archivo. Por esto, en este archivo queda una historia de la personalización/módulo. Incluso desde este puede modificar tablas o datos que no son de su personalización, aunque no es recomendable y de requerirlo se sugiere seguir las indicaciones antes dadas para personalizaciones de las fuentes genéricas (por ejemplo deshabilitar registros de tablas básicas en lugar de borrarlos).

Como el propósito de los archivos sitios/sivelper/estructura.sql y sitios/sivelper/datos.sql es inicializar nuevas bases de datos, estos deben reflejar el estado final de las tablas que maneja la personalización después de ejecutar sitios/sivelper/actualiza.php, pero estos archivos no incluyen la historia de cambios que si debe estar presente en sitios/sivelper/actualiza.php para poder actualizar instalaciones con versiones previas. El archivo sitios/sivelper/prepara-indices.sql será ejecutado tanto al inicializar una base como al actualizar.

Si su personalización consiste en nuevos reportes que no modifican ni requieren nueva información en bases de datos, basta que cree nuevas fuentes en PHP y las referencie desde nuevas opciones del menú (incluyendolas desde sitios/sivelper/datos.sql y también desde sitios/sivelper/actualiza.php), tal como hace el módulo modulos/estrotulos.

Si su personalización maneja nuevos datos, se sugiere que lo haga en tablas nuevas (de requerirlo piense en extender tablas existentes usando la misma llave primaria en la nueva tabla), las nuevas clases descendientes de DB_DataObject ubiquelas en el directorio DataObjects de su personalización (e.g sitios/sivelper/DataObjects). Para agregar una nueva tabla tenga en cuenta:

La nueva información la puede solicitar en una nueva pestaña del formulario de captura como puede ver a manera de ejemplo en el módulo etiquetas y en particular en modulos/etiquetas/PagEtiquetas.php

Es posible extender pestañas de la ficha de captura o refinar la forma como se generar para incluir nuevos campos. Un ejemplo lo puede ver en el módulo anexos en modulos/anexos/PagFrecuenteAnexo.php que extiende la pestaña Fuentes Frecuentes, así como la tabla subyacente (Escrito_caso).

Algunas recomendaciones para crear o extender pestañas son:

Como orden posible para realizar pruebas después de hacer cambios se sugiere:

  1. Vea que la interfaz sea como la espera modificando la constructora de la clase y las funciones iniVar, nullVar, formularioAgrega y formularioValores.

  2. Verifique que se procesen los datos examinando la base de datos después de cambiarse de pestaña en la función procesa. Note que tras procesar cada pestaña debe llamarse la función funcionario_caso

  3. Agregue instrucciones para eliminar en las funciones eliminaDep y elimina.

  4. Agregue información para búsquedas desde Consulta Web en la función datosBusqueda.

  5. Agregue método para exportar a relato (seguramente en observaciones) en la función aRelato, así como para importar en la función importa.

Puede resultar convenientes activar mensajes de depuración de DataObject poniendo en 5 la opción 'debug' en el archivo sitios/sivelper/conf.php

Notas

[1]

Puede sincronizar con las facilidades más recientes ejecutando DREPASA=/hoome/miusuario/structio/repasa herram/fixldevdbrep.sh cambiando la ubicación de las fuentes de repasa en la variable DREPASA.