# 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 ) 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`; 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 . 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 ) ampliados con reglas de nomenclatura de silverorange (ver 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 ), 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

## Internacionalización

Para actualizar traducciones desde el directorio con fuentes ejecute:

    make trad

## 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 ), 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 .

## Documentación de usuario

Se emplea DocBook con las facilidades de repasa 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`.. Está disponible en formato HTML en .

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 . Un esobozo de arquitectura se presenta en la siguiente figura (completamos los diagramas de ).

Esbozo de Arquitectura

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

## 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)

### 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 ). 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 .

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.

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

### 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 ) empleando diversas librerías de Pear (ver ), 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 ).

`DB_DataObject`

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

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

## Base de Datos

En cuanto a base de datos la estructura en SQL (ver ) 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 ).

Estructura de la Base de Datos

## 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`