6. Modificaciones a las fuentes
Anterior Capítulo 6. Personalización Siguiente

6. 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 Sección 4, “Pruebas de regresión”) 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).

6.1. 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; los nombres de tablas no llevan espacio ni _, excepto tablas que relacionan otras 2 en cuyo caso se separan las tablas ordenadas alfabéticamente separadas con '_' como sugieren las convenciones de CakePHP (ver [nomcakephp]. Los nombres de campos no llevan espacios ni _, excepto que una llave foranea de la tabla t puede ser id_t --aunque un campo que referencie llave de otra tabla puede tener un nombre diferente cuando se requiera aclarar. 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.

Las fuentes en Javascript seguirán la guía de estilo de Google [javascriptgoogle]

6.2. Internacionalización

Para actualizar traducciones desde el directorio con fuentes ejecute: 

make trad

6.3. 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.2/tec/.

6.4. Documentación de usuario

Se emplea DocBook con las facilidades de repasa[7]. 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

6.5. 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 Sección 1, “Recurso Humano”. Un esobozo de arquitectura se presenta en la siguiente figura (completamos los diagramas de Sección 2, “Infraestructura Tecnológica”).

Esbozo de Arquitectura

6.6. Control de versiones

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

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

git clone https://github.com/pasosdeJesus/SIVeL.git

La versión 1.2 está en la rama "master" y se emplean etiquetas para marcar versiones menores de esta cuando se publican.

Los desarrolladores con permiso de escritura pueden usar:

  • herram/gitact.sh Para actualizar.

  • herram/gitcommit.sh Para agregar cambios.

6.7. Organización de fuentes

Las extensiones empleadas a lo largo de las fuentes son:

  • .htaccess: Para controlar opciones de Apache y típicamente evitar listar directorios desde el web.

  • .awk: programa para awk usado desde línea de comandos.

  • .bitacora: Bitacora de pruebas de regresión.

  • .css: Hoja de estilos en cascada CSS usado desde interfaz HTML.

  • .copia: Copia de respaldo.

  • .dsl: Hoja de estilos DSSL usado para generar documentación a partir de fuentes en DocBook.

  • .empty: Archivo de configuración de fuentes con valores por defecto.

  • .ent: Entidades para parametrizar fuentes de documentación en Docbook.

  • .espreg: Resultado esperado en prueba de regresión.

  • .gif: Formato para animaciones mientras apng o mpg son mejor soportados.

  • .grep: Patrones por buscar con grep.

  • .html: Documento HTML, partes de la interfaz web.

  • .ico: Icono para presentar en sitio web.

  • .ini: Configuración de base de datos.

  • .ispell: Diccionario para ispell.

  • .jpg: Formato gráfico con pérdidas y alta compresión.

  • .js: Fuente en Javascript.

  • .mak y Makefile: Archivos para construir aplicaciones o distribuciones o documentación.

  • .odt: Documentación en Open Document Format.

  • .php: Fuente en PHP, la mayoría para ser empleadas desde la aplicación web, aunque por ejemplo las pruebas de regresión se ejecutan desde la línea de comandos.

  • .plantilla: Fuente con variables de configuración por defecto, para copiar y modificar.

  • .png: Formato gráfico sin perdidas.

  • .pot: Fuente de de localización.

  • .pot: Localización compilada.

  • .sed: Instrucciones para el Stream Editor sed.

  • .selenio: Pruebas de regresión para Selenium.

  • .sh: Archivos de comandos para ser ejecutados por el interprete de comandos.

  • .sql: Instrucciones SQL para un motor de bases de datos que soporte ese estándar.

  • .svg: Gráficas en formato vectorial.

  • .txt: Documentación como texto plano.

  • .xdbk: Fuentes de documentación en DocBook XML.

  • .xcf: Gráfico para editar con GIMP

  • .xml: Archivo de configuración en XML.

  • .xrlt: Relato en XML en formato del SINCODH.

  • .xsl: Hoja de estilo XSL.

Además durante la configuración y la generación de documentación se generan archivos con las siguientes extensiones:

  • .dvi: Formato de salida del programa TeX (sigla de Device Independent).

  • .pdf: Formato para documentos digitales (sigla de Portable Document Format)

6.7.1. 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 Sección 2, “Labores administrativas desde el interprete de comandos”.

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

El archivo de comandos herram/trans.sh ayuda a aplicar transformaciones automáticas a las fuentes definidas en herram/trans.sed y herram/trans.awk.

El archivo de comandos herram/geo/dump-a-datos.sh genera un volcado de la información geográfica incluida en la base.

El archivo de comandos herram/incl.sh genera un grafo de inclusión de las fuentes en el formato de Graphviz.

6.7.2. 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 Sección 4, “Pruebas de regresión”.

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

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

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

6.8. 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 Sección 6.3, “Documentación técnica”)

6.9. 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 con visql y producido con GraphViz (ver [graphviz]).

Estructura de la Base de Datos

6.10. 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:

  • Agregue la definición en sitios/sivelper/estructura.sql. Si agrega una tabla básica hagála descendiente de DataObjects/Basica.php que incluirá los campos id, nombre, fechacreacion y fechadeshabilitacion.

  • Agregue código que cree las nuevas tablas y los nuevos datos en sitios/sivelper/actualiza.php como un bloque digamos con identificación mip-1. En instalaciones que ya operan de SIVeL este es el código que efectivamente será utilizado para activar su personalización.

  • Agregue datos en sitios/sivelper/datos.sql así como registros en la tabla ActualizacionBase con la(s) identificación(es) que haya agregado en sitios/sivelper/actualiza.php (en este ejemplo mip-1); esto lo puede hacer brevement con la función aplicaact. Si añadió índices (por ejemplo para tablas básicas) añada actualización para este en prepara_indice.sql, eventualmente con un índice máximo para datos reservados (las personalizaciones emplearan índices superiores).

  • Agregue llaves de las nuevas tablas en sitios/sivelpear/DataObjects/estructura-dataobject.ini e integridad referencial en sitios/sivelpear/DataObjects/estructura-dataobject.links.ini --en el primero los códigos resultan de la suma de: 

    1 INTEGER
2 VARCHAR o TEXT
4 DATE
8 TIME
16 BOOLEAN
32 LOG TEXT
64 BLOB
128 NOT NULL

    A partir de estos archivos junto con los de SIVeL básico y los de otros módulos se crean los archivos de un sitio tanto al actualizar con actualiza.php como desde la línea de comandos con el script bin/creaesquema.sh que debe ejecutarse desde el directorio del sitio.

  • En el directorio sitios/sivelper/DataObjects cree un archivo con datos de tabla como descendiente bien de DataObjects/Basica.php (si es tabla básica, ver por ejemplo Etnia.php) o de DB_DataObject_SIVeL.php (ver por ejemplo Profesion_comunidad.php). El nombre debe ser el mismo de la tabla pero con la primera letra mayúscula y las demás minúsculas. Se recomienda consultar documentación de clases base mencionadas.

  • Las tablas básicas se declaran en el arreglo menu_tablas_basicas que se define en el archivo de configuración de cada sitio conf.php, este arreglo puede ser completado durante la ejecución. Entonces si tiene información parametrizable como para una tabla básica, debe tener una nueva pestaña o una extensión de una pestaña existente en la que declare la función actGlobales() que añada la tabla a las básicas. Vea un ejemplo en el módulo modulos/etiquetas/PagEtiqueta.php que añade la tabla básica Etiqueta cuando se activa el módulo. Una vez agregue la agregue puede probar inserción, eliminación de registros desde el menú Administración->Tablas Básicas.

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:

  • Cada pestaña corresponde a un archivo con una clase que extiende PagBaseSimple o PagBaseMultiple o una pestaña existente. El nombre comienza con Pag (PagMemo.php es uno simple para comenzar). También puede ver la descripción de las funciones por definir en PagBaseSimple (ver documentación técnica)

  • Algunos detalles de la presentación de la información de una pestaña se determinan en las clases que corresponden a tablas, y que son descendientes de DB_DataObject. Los detalles por cuadrar los específica la librería DB_DataObject_FormBuilder. En estas mismas clases puede cuadrar otros detalles con las funciones preGenerateForm y postGenerateForm que se llaman antes y después de generar el formulario.

  • Si necesita agregar o eliminar pestañas asegure que se referencian las pestañas en el orden que se desean en la variable ficha_tabuladores de sitios/sivelper/conf.php.

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 caso_usuario

  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


[7] 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.

Anterior Subir Siguiente
5. Crear sitio Inicio 7. Algunos lineamientos de seguridad informática