Conceptos Clase Procedimiento (pro)

ejemplos Bases de ejemplo: test-informes

Permiten ejecutar desde la aplicación Ingrid cliente un programa javascript que puede realizar acciones en el cliente o en el servidor (utilizando las funciones publicadas por este). Estas acciones pueden ser operaciones sobre la BD, como búsquedas que muestran una lista de conceptos en pantalla, generar informes en formato html (para imprimir a formato PDF desde el navegador), imprimir archivos, operar con los archivos del directorio de la BD en el servidor, importar y exportar datos de la base, manejar datos de varias bases...

En el tema Anexo: API de programación en javascript se encuentra la documentación de las funciones que se pueden utilizar.

 

La programación tiene que ser asíncrona tanto en los accesos a BD, como en otros procesos en los que no se puede garantizar el tiempo de respuesta (o si habrá respuesta).

En la BD ingrid-comun, existe una biblioteca de informes que se pueden usar desde una BD cualquiera como si estuviesen en ella, de 4 formas distintas:

- haciendo una llamada a ellos en un script de nuestra BD

- si aparecen como informes contextuales a alguna clase de nuestra BD

- con una referencia especial que consiste en crear un concepto de clase procedimiento y poner el mismo nombre del informe en el comun, con el _id acabado en ".comun", como: pro.con1.comun

- desde la persiana de Base > Procedimientos comunes

Los usuarios no administradores, sólo ven una persiana con los parámetros que se pueden modificar y un botón Procesa para ejecutar el script. El resto de las opciones a continuación sólo las definen los administradores.

Definición de Parámetros

En cada concepto de esta clase, a la manera de la definición de campos en el modelos de datos, se pueden definir distintos campos que sirven para introducir datos variables en la ejecución de cada script. Se pueden usar los mismos tipos de campos de que en la definición de clases. Además, los informes contextuales incluyen por defecto el parámetro 'con', y el parámetro 'bus' en los informes múltiples, que hacen referencia al concepto actual o a la selección de conceptos, desde el que se ha lanzado.

En la esquina superior derecha de la persiana Parámetros (donde se introducen), el botón Pone parámetros por defecto, carga los valores puestos en cada parámetro, en su campo Valor de defecto. Además, si es la primera vez que se entra en el informe y no hay memoria de los datos introducidos en los parámetros, se ponen inicialmente los valores de defecto.

Impresión exacta a formato PDF

Es la forma más adecuada para imprimir fichas y listados (datos en tablas cuyas columnas se extienden a lo largo de varias páginas), incluso con fotografías e imágenes de mapas, con cabeceras con logotipos y pies de página que se repiten en todas las páginas. Se hace imprimiendo exactamente a un formato de página, es decir, con informes enfocados a la impresión en papel, aunque se genera un PDF que se puede guardar le cliente en la máquina local, o almacenar en BD, etc..

 El informe se calcula y genera en el navegador del cliente, y utiliza los comandos de impresión del lenguaje de PDF, lo que garantiza exactitud en la salida.

Impresión de una página html en papel o PDF, desde los navegadores

La impresión en formato html es la aconsejada principalmente para imprimir mapas interactivos (temáticos o de inventario, por ejemplo, con fondos Leaflet, donde podemos desplazarnos y hacer zoom en el mapa de la página-informe resultante). Para impresiones masivas de decenas o centenares de fichas, informes muy extensos en páginas o cualquier informe habitual de consulta que no tenga componentes interactivos, se recomienda la impresión directa en PDF:

Cualquier informe mostrado en la persiana Resultado de un concepto de tipo Procedimiento, permite varias acciones con los botones de la esquina superior derecha de la persiana . En una pestaña independiente del navegador se puede:
- Presentar como texto el contenido html de la página
- Presentar en ventana independiente el mismo informe
- Descargar el archivo html para guardar en local, enviarlo por e-mail, etc.

Con la opción imprimir de los navegadores, podemos abrir estos archivos .htm e imprimirlos en papel o mandarlos a una impresora PDF, con lo que se guardan como un archivo en ese formato.

Chrome.- es el que más posibilidades de configuración tiene. Seleccionando como impresora Guardar como PDF y abriendo la sección Más opciones, podemos seleccionar un tamaño de papel más grande que el destino real (por ejemplo A3 para imprimir en un papel DIN-A4) de forma que se imprima con mayor calidad y fuentes y gráficos más reducidos. Puede compararlos, viendo un informe de ejemplo en tamaño A4 y el mismo guardado con tamaño A3. También se puede jugar con el Diseño de página (hor/vert) del archivo a guardar y con el campo Escala. El mismo tamaño A3 al 200%,

Internet Explorer.- permite controlar fielmente el tamaño de salida. Por ejemplo al imprimir un PDF en tamaño A3 e imprimir en un papel tamaño A4 vertical, se mostrará con una proporción como si se hubiese impreso en 2 papeles A4 en formato apaisado, uno encima del otro. Puede ver la diferencia con el guardado en tamaño A4.

Firefox.- permite pocas modificaciones: tamaño y orientación de página.

Persiana Particulares

La configuración global se define en la persiana Base > Procedimientos

Informes contextuales

En el menú contextual de cualquier página , se muestran los informes asociados a esa clase, mediante el campo de procedimientos Clase asociada, accesible sólo para administradores.

Además de los informes de la propia base, se muestran todos los de la base ingrid-comun que estén asociados a esa clase. El código de procedimiento se muestra on un prefijo "comun." delante, que indica que se ejecutan como si estuviesen en la base actual, y sobre los datos de la base actual, pero con el código javascript leído de la base ingrid-comun.

El conmutador Autoprocesa marcado, hace que nada más entrar en la página del informe, se ejecute automáticamente, sin tener que pulsar el botón Procesa. Esto es cómodo para scripts de búsqueda, por ejemplo. 

El conmutador Múltiple, indica que admite no sólo un identificador actual, sino una lista de ellos (cuando son todos de la misma clase), y por tanto, se mostrará de forma contextual, también con una lista de conceptos de los indicados como clase. En la base de ejemplo test-informes, una muestra la tenemos en pro.con2 · Listado de conceptos.

Eventos

Además de los eventos generales de la clase .pro, que se aplicarían a todos los scripts, en esta persiana se pueden definir eventos concretos para cada procedimiento.

API utilizable en la definición del programa

En la persiana Definición de Programa, se puede editar código javascript usando todas las funciones de todas las librerías del cliente web Ingrid 8.

Antes de la ejecución de las siguientes funciones, se ejecutan los eventos de la persiana Definición de Evento: function(bas,pro,vals,cb), cuyo contenido será incluido dentro de una función con ese nombre y parámetros) y también la persiana Definición de parámetros, que alimenta con variables inicializadas, calculadas, dependientes unas de otras, etc. la ejecución del script principal:

function (bas,inf,cb){...} - La ejecución de cada concepto de clase script (inf) se ejecuta dentro de una función que recibe como parámetros la base, el propio concepto actual y una función de callback donde devolver el resultado.

inf.pars:{cod: {tip,cod,res,...}} - En la persiana de administrador definición de parámetros, se puede crear una lista de campos con los mismos tipos de campos que la BD, y que aparecerán como datos de entrada al procedimiento en la persiana Parámetros.

Ejemplo. El script:

function(bas,pro,vals,cb)
{
  writelineLimpia (vals);
  writeline (vals.fec); 
  cb() 
}

imprime (limpiando la salida anterior), el contenido de la definición de valores, y el siguiente writeline, imprime uno de ellos (el valor fec) que se devuelve en forma de un objeto json con el valor introducido en el control de calendario, como:

{"fec":20160416}

vals.cod - Recupera los valores introducidos en los campos de parámetros del procedimiento.

cb({salida: mensaje}) - La devolución en la función de retorno, puede incluir salida por un panel de log (texto), en formato html, un diálogo, una lista de conceptos... siendo la salida una de estas variables:error: presenta dato como texto de error en el panel de salida de errores al final de la página [ERROR]
input: presenta datos en TEXTAREA [Informe de texto]
texto: presenta datos si PRE, sin formato [Informe de texto]
div: presenta datos en DIV [Informe HTML(div)]
body: presenta datos como cuerpo HTML, utiliza estilos de Ingrid [Informe HTML(body)]
html: presenta datos como documento HTML [Informe HTML]
docl: presenta lista de conceptos [Búsqueda de documentos]
si ninguno de los anteriores: presenta data [Informe]

Buenas prácticas

Hay que tener precaución cuando se realizan búsquedas desde script directas contra el motor, porque no se cumplen los criterios de filtro de puede poner el interface en clases de búsqueda o en la herramientas de búsqueda. Por ejemplo, en una BD con 25.000 registros de arbolado cuya ficha tiene 30 campos, esta búsqueda en un script puede tardar varios segundos y conllevar un tráfico enorme en registros recuperados y volumen de datos (recupera todos los campos):

bas.leeConceptos ('cla=jararb', cb);

Lo correcto sería filtrar sólo una pequeña cantidad de resultados (la lista luego permitirá el scroll para ir recuperando poco a poco) y filtrar sólo los campos que necesitemos:

bas.leeConceptos ( {find:'cla=jararb ', limit:100, data:{_id:1,res:1,nid:1,espi:1,espung:1,pert:1,diamc:1,altt:1,alt1c:1}}, cb);

Herramientas para informes

Los informes estándar se generan casi siempre en formato html, que es imprimible en formato PDF desde el navegador. también hay una herramienta basada en el webkit de Chrome, que permite utilizar una función de Ingrid para generar directamente un archivo PDF desde un informe construido en html, y que se guardará en el directorio \ima\originales del proyecto.

Este es un componente libre que a 4/4/17 está en la versión estable 0.12.4