Escritos

Introducción

A la hora de crear un documento en ODL es necesario hablar de ciertos conceptos que intervienen en este tipo de operaciones. Por un lado están las definiciones de componentes documento y plantilla, y por otro lado existe un formato de fichero .rtf (Rich Text Format) que contendrá la información necesaria para crear el escrito.

Este tipo de ficheros ofrece la posibilidad de declarar marcas en el contenido, de forma que esas marcas sean sustituídas por la información que pueda estar contenido en los campos seleccionados.

Veamos con más detalle cada uno de los conceptos:

Componente documento

La definición de documento se realiza a nivel de contenedores. Este componente lo definiremos en aquel contenedor en el cual queramos que aparezca la opción de elaboración de escrito.

Para esta definición existe sólo un atributo, plantilla_documento, que especificará el fichero .RTF asociado. En ODL, el recurso contenedor sólo permite una definición de documento, por lo que no podremos generar varios escritos a raíz de un mismo objeto.

Componente plantilla

Una plantilla es un componente de ODL donde definiremos, mediante secciones, los campos a rellenar en el fichero .rtf. La plantilla tomará los valores de los campos mediante referencia.

Pero, ¿y cómo sabe la plantilla a qué documento tiene que enviar esos campos?

Existe un atributo documento donde especificaremos la definición de la componente documento que, a su vez, tendrá declarado el nombre del fichero .rtf. Podríamos decir que la componente documento actúa como puente de comunicación entre la plantilla y el documento .rtf.

Rich Text Format

Es el formato que utiliza egeasy para la creación de escritos. Este formato permite definir unas marcas o tags (definidas específicamente para ODL), de forma que podamos crear un escrito dinámico, cuyo resultado o contenido puede variar en función de la información contenida en una plantilla.

Elaborar un escrito

Aprovechando el ejemplo utilizado en el artículo contenedores, vamos a incluir código ODL para que podamos elaborar un escrito.

En primer lugar, debemos tener claro la estructura e información que contendrá nuestro escrito, para así poder definir las marcas que necesitemos. Para este ejemplo básico, y utilizando la definición del contenedor Libro, queremos generar simplemente una ficha con los datos de un objeto Libro. Por tanto, necesitaremos elaborar un fichero .rtf con el contenido y sus marcas, definir la componente documento en el tipo de contenedores que nos interese elaborar los escritos y, finalmente, definir la plantilla con los campos correspondientes. Veamos pues cómo definimos las marcas en nuestro fichero .rtf para que al elaborar el escrito, se traduzcan en valores concretos:

Documento RTF con marcas

Esta es la marca más básica que puede integrar un documento .rtf. Su sintaxis, <#=Nombre del campo>, es muy simple. La marca completa será sustituída por el valor del campo, y para eso, el nombre de la marca debe coincidir con el campo incluído en la plantilla. Una vez creado el documento .rtf, tenemos que declarar la componente documento en el contenedor desde donde queremos crear el escrito:

tipo [Libro] es contenedor
   [Datos] es formulario
   ...
   ...
   ...
   fin

   [Escrito] es documento
       -plantilla_documento = "Escrito_001.rtf";
   fin

fin

Como ya explicamos anteriormente, en el atributo plantilla_documento especificamos el documento .rtf con el que se va a generar el escrito. Veamos cómo se refleja el código insertado en la herramienta egExplorer:

Inclusión de la componente documento en un objeto

Como vemos, nos aparece una pestaña nueva al abrir un objeto de tipo Libro, que obtiene el nombre de la definición de documento. En esta instancia del objeto, podremos elaborar y abrir los escritos que se generen.

Ahora solamente nos falta definir la componente plantilla. Esta componente, no hay que definirla dentro de un contenedor como la definición de documento, sino que declararemos un tipo plantilla como código independiente de cualquier definición de contenedor.

tipo [Elaborar Escrito] es plantilla
   -documento = [Libro].[Escrito];
   [Campos a rellenar] es seccion
      [Enlace] es variable
         -vinculo.definicion = [Libro];
         -edicion.modo = referencia;
         -edicion.valor = [&Dominio];
      [Código] es texto
         -edicion.modo = referencia;
         -edicion.valor = [Enlace]->[Datos].[Código];
      [Título] es texto
         -edicion.modo = referencia;
         -edicion.valor = [Enlace]->[Datos].[Título];
      [Autor] es texto
         -edicion.modo = referencia;
         -edicion.valor = [Enlace]->[Datos].[Autor];
      [Tipo] es texto
         -edicion.modo = referencia;
         -edicion.valor = [Enlace]->[Datos].[Contenido].[Tipo];
   fin
fin

Hemos incluído los campos que se corresponden con las marcas definidas en el fichero .rtf y que serán los encargados de almacenar los valores del objeto que luego sustituirán a las marcas en el .rtf.

Como habrás observado, hay definida una variable. En este caso, la variable obtiene el valor [&Dominio], cuyo valor será la ubicación del recurso, en este caso, la ubicación del contenedor Libro. Su declaración no es estrictamente necesaria, ya que podríamos eliminar la variable y sustituir la referencia a los campos de esta forma, [&Dominio]->[Datos].[Campo].

Veamos entonces cómo se produce la obtención de valores por parte de la plantilla y su posterior sustitución en el .rtf:

Cumplimentar el documento mediante la plantilla

Una vez aceptado el cumplimentado, se abrirá el documento con los valores intercambiados. El documento ya estará creado, y el resultado sería el siguiente:

Sustitución de los valores proporcionados por la plantilla en el documento .RTF

Hay que tener en cuenta un último aspecto.

Ya sabemos que cuando elaboramos un escrito, las marcas que correspondan serán sustituídas por los valores de la plantilla. Ahora bien, si modificamos algún campo del objeto cuya marca ya ha sido sustituída por una elaboración de escrito anterior, y volvemos a elaborar otro escrito, el cambio de valor del campo no se reflejará en el escrito, debido a que la marca ya no se encuentra.

Otro caso es que al elaborar un escrito, dejemos una marca sin sustituir, debido a que el campo asociado carezca de valor alguno. Si posteriormente insertamos algún valor a ese campo, y volvemos a elaborar el escrito, entonces la marca sí será sustituída por el valor del campo.

Firmando escritos

En los sistemas de información, es una tarea común firmar los escritos o informes que se generan. Para ello, ODL proporciona un campo firma que ofrece la posibilidad de insertar firmas en los escritos.

Para poder insertar firmas en un escrito, es necesario definir un campo firma en el formulario del contenedor desde donde elaboramos el escrito. Además, debemos insertar la marca correspondiente en nuestro escrito, que será sustituída por una imagen .bmp que habremos asociado al usuario firmante mediante la aplicación egAdmin.

En el caso de las firmas, no es necesario insertar el campo en ninguna plantilla, ya que la elaboración de un escrito y la realización de una firma se consideran acciones distintas. En la práctica, normalmente el usuario que elabora el escrito no es el encargado de realizar la firma, de forma que no tiene sentido incluirla en la plantilla. Veamos el siguiente ejemplo:

tipo [Libro] es contenedor
   [Datos] es formulario
      [Código] es timbre
         -certificado.valor = [&Valor_secuencia];
         -certificado.secuencia.nombre = "STR$LIBRO";
         -certificado.secuencia.longitud = 4;
      [Título] es texto
      [Autor] es texto
      [Edición] es texto
      [Editorial] es texto

      [Contenido] es seccion
         [Tipo] es texto
            -edicion.valores = $Matriz("Literario","Biografía","Científico","Infantil");
            -apariencia.desplegable = verdadero;
         [Sinopsis] es texto
            -edicion.longitud = 1000;
      fin
      [Firma1] es firma
   fin
   [Escrito] es documento
       -plantilla_documento = "Escrito_001.rtf";
   fin
fin

Añadir campo firma en el documento .RTF. La plantilla asociada a este escrito incluirá los campos correspondiente a las marcas indicadas en la imagen, pero no el de la firma.

A la hora de sustituir un campo firma, además de la imagen también se incluyen ciertos datos relacionados con el firmante, también denominados rúbricas. Por defecto, el formato firma de un usuario está compuesto de los campos pie de firma, cargo del usuario, la imagen de la firma y el nombre del usuario, por este orden. Si generamos un escrito con la marca anterior, el resultado sería el siguiente:

Primer paso: elaborar escrito

Segundo paso: realizamos la firma

Tercer paso: abrir el documento resultante

Cuando existe un campo firma que ha sido firmado, y se guarda el objeto, ya no será posible elaborar más escritos. El objeto quedará bloqueado, de forma que los campos ya no serán editables.

Para poder editar un campo cualquiera una vez firmado un campo firma, haremos uso del atributo edicion.proteger. En el capítulo 6 de este artículo podremos ver la utilidad de este atributo.

Propiedades de un campo firma

Como hemos dicho, la inclusión de una firma en un escrito incluye además una serie de datos relacionados con el firmante. Estos datos son realmente propiedades del campo firma, que adquieren valor una vez se firma el escrito. Estas propiedades son las siguientes:

• Fecha: indica la fecha en la cual se realizó la firma. Ésta se muestra en formato largo, es decir, con la forma "__ de _________ de ____".
• Usuario: nombre del usuario que realizó la firma.
• ID_Usuario: identificador del usuario que realizó la firma.
• Sede: sede del usuario que realizó la firma.
• Pie_de_firma: delegación de responsabilidad a la cual pertenece el usuario que realizó la firma.
• Cargo: cargo del usuario que realizó la firma.

Las propiedades Usuario, Sede, Pie_de_firma y Cargo son campos editables en la ficha de cada usuario y que podremos modificar mediante el egAdmin.

Pero, ¿y si quisiéramos insertar en el escrito algún dato adicional del campo firma?

En ODL, la forma de acceder a las propiedades, en este caso, de un campo, es la siguiente: Campo.&Propiedad. Por tanto, si quisiéramos insertar la información de la propiedad Sede o Fecha pues sólo tendríamos que añadir las siguientes marcas en nuestro escrito: <#=Nombre del campo firma.&Sede> ó <#=Nombre del campo firma.&Fecha>.

Incluyendo varias firmas en un escrito

En un sistema de información, es normal que un escrito, ya sea un informe, una resolución, etc., tenga que ser firmado por varias personas responsables. En caso de ser así, la solución es simple, añadir tantos campos firma en el formulario como firmas se tengan que realizar en el escrito, con sus respectivas marcas en el fichero .rtf asociado.

Ahora bien, ¿es posible que para realizar una firma se requieran otras? Aunque los campos firmados se puedan ver en el objeto, es posible que interese que se reemplacen en el escrito aunque no se hayan timbrado todas las firmas. Veamos qué atributo nos permite adoptar este comportamiento.

Atributo reemplazar_siempre

Es un atributo que permite que las firmas sean sustituídas en el escrito al momento de realizarlas. Es un atributo lógico, que por defecto adquiere el valor falso, de forma que las firmas serán reemplazadas en el escrito cuando se realicen todas las firmas. Lo añadiremos con valor verdadero en aquellos campos firma que queramos se reemplacen en el momento de realizar la firma, independientemente del estado de otros campos firma.

Ejemplo

Como ya hemos dicho, en caso de no especificar el atributo reemplazar_siempre, su valor será falso y por tanto las firmas se reemplazarán una vez se hayan realizado todas. Por el contrario, veamos como cambiaría el comportamiento de las firmas en caso de incluir el atributo con valor verdadero:

tipo [Libro] es contenedor
   [Datos] es formulario
      [Código] es timbre
         -certificado.valor = [&Valor_secuencia];
         -certificado.secuencia.nombre = "STR$LIBRO";
         -certificado.secuencia.longitud = 4;
      [Título] es texto
      [Autor] es texto
      [Edición] es texto
      [Editorial] es texto

      [Contenido] es seccion
         [Tipo] es texto
            -edicion.valores = $Matriz("Literario","Biografía","Científico","Infantil");
            -apariencia.desplegable = verdadero;
         [Sinopsis] es texto
            -edicion.longitud = 1000;
      fin
      [Firma1] es firma
         -reemplazar_siempre = verdadero;
      [Firma2] es firma
   fin
   [Escrito] es documento
       -plantilla_documento = "Escrito_001.rtf";
   fin
fin

• Realizamos la primera firma del formulario:

Campo Firma1 firmado

• Al abrir el documento, veremos que la primera firma sí se ha reemplazado, de forma que la marca de la segunda firma, aún queda pendiente:

Efecto que produce el atributo reemplazar_siempre. La primera firma se ha sustuído en el escrito

• Realizamos la segunda firma:

Timbrado de la segunda firma

• Y finalmente se genera el documento con las dos firmas:

Reemplazo de la segunda firma

En este caso, las firmas las ha realizado el mismo usuario a modo de ejemplo. Pero no suele ser lo normal. Los procesos por los que va pasando un documento requieren firmas de diferentes responsables, y por tanto, de diferentes usuarios dentro de egExplorer.

Atributo actualizar_escrito

Es posible que se den casos en los que el valor de un campo se asigne una vez firmado un escrito y por tanto, su objeto protegido. La marca correspondiente a ese campo, no habrá sido sustituída aún en el escrito, pero al estar el objeto protegido por la firma, no será posible asignarle un valor al campo, elaborar informe y sustituir el valor por la marca.

Para estos casos, utilizaremos el atributo actualizar_escrito, que nos permite actualizar un valor por su marca en el escrito, aunque el objeto esté protegido.<p>Es un atributo lógico, al que podemos asignarle una expresión lógica, que tiene como valor por defecto "falso". Para activarlo, se le asignará "verdadero" en el campo que nos interese realizar la sustitución.

Pero para poder realizar la edición de un campo en un objeto protegido(su escrito está firmado o timbrado), debemos hacer uso del atributo <code>edicion.proteger = falso;</code>, que nos permite editar un campo cuando el objeto en el que está contenido, está protegido. Por tanto, estos dos atributos deberán incluirse conjuntamente para lograr este comportamiento con los escritos.

Marcas en un fichero de texto enriquecido

Como ya sabes, un fichero .RTF incluye unas marcas en su contenido, de forma que son sustituídas por valores al elaborar un escrito. En los ejemplos anteriores ya hemos utilizado un tipo de marca, la más básica, que es sustituir un campo por un valor. Pero existen otras marcas que ofrecen más posibilidades a la hora de crear un escrito. Veamos a continuación qué tipos de marca podemos incluir y cuál es su funcionamiento:

Sustitución de una expresión por un valor

Es la marca más básica, y la que hemos estado utilizando en los ejemplos anteriores. La marca será sustituída por el valor que contenga el campo.

<#=Nombre del campo>

Sustitución de un bloque según condición

Es posible que nos interese incluir un bloque de texto pero solamente cuando se cumpla cierta condición. Aquella condición que pueda soportar el lenguaje ODL, será soportada en esta marca, ya sea utilizando campos, funciones de librería, etc. La sintaxis de esta marca sería la siguiente:

<Block Nombre del bloque [Nombre del campo] = ' Valor ' > Contenido a sustituir <\Block Nombre del bloque>

Siempre que estemos haciendo la comparación con valores de tipo texto, emplearemos las comillas simples para acotar el valor.

Otro aspecto a tener en cuenta es que el contenido del bloque a sustituir puede incluir otras marcas, de forma que podamos crear estructuras de texto más complejas.

Generar una tabla en el escrito mediante un campo tabla

Imaginemos que tenemos un campo tabla en un formulario, con sus respectivas columnas, y queremos plasmar esa tabla en el escrito, con sus correspondientes valores. Para ello, existe también una marca:

<table Nombre de la tabla>Diseño de la tabla<\Nombre de la tabla>

Entre la marca de apertura y la marca de cierre, se debe diseñar la tabla en el documento. Se diseñará una tabla con dos filas. ¿Por qué dos filas? Porque la primera fila la toma para introducir los títulos de cada columna, y en la segunda fila añadiremos la marca que corresponda con cada campo columna de la definición de tabla.

No obstante, abarcaremos este tema en el ejemplo que veremos al final de este documento.

Listar los valores de una columna

En ocasiones, es posible que nos interese listar ciertos valores que corresponden a la columna de una tabla. Para conseguir este comportamiento, existe otra marca cuya sintaxis es la siguiente:

<#=Nombre del campo tabla.Nombre de la columna>

El resultado será un texto con la lista de los valores de la columna separados por comas. El último valor estará precedido de la conjunción "y" en vez de una coma ("...valor1, valor2, valor3 y valor4...").

Lógicamente, tanto el campo tabla como la columna tendrá que ser referenciada en la plantilla.

Ejemplo

A continuación vamos a realizar un escrito .rtf donde podamos probar las marcas explicadas.

Partiendo de nuestro contenedor Libro, veremos qué modificaciones tenemos que hacer en nuestro contenedor y plantilla para que la inclusión de las marcas en el escrito tengan el efecto deseado. Para empezar, crearemos el modelo de escrito .rtf, con su contenido y sus marcas. Es fundamental realizar al principio este paso, ya que las marcas nos indicarán qué aspectos habrá que modificar o añadir en el contenedor y en la plantilla

Elaboración del documento .RTF

Una vez creado, necesitamos añadir un campo tabla a nuestro contenedor Libro, llamada Libros similares que esté compuesta por tres columna, Nombre del libro, Autor del libro y Año de publicación:

tipo [Libro] es contenedor
   [Datos] es formulario
      [Código] es timbre
         -certificado.valor = [&Valor_secuencia];
         -certificado.secuencia.nombre = "STR$LIBRO";
         -certificado.secuencia.longitud = 4;
      [Título] es texto
      [Autor] es texto
      [Edición] es texto
      [Editorial] es texto
      [Contenido] es seccion
         [Tipo] es texto
            -edicion.valores = $Matriz("Literario","Biografía","Científico","Infantil");
            -apariencia.desplegable = verdadero;
         [Sinopsis] es texto
            -edicion.longitud = 1000;
      fin
      [Libros similares] es tabla
         [Nombre del libro] es texto
         [Autor del libro] es texto
         [Año de publicación] es texto
      fin
   fin
   [Escrito] es documento
       -plantilla_documento = "Escrito_001.rtf";
   fin
fin

Una vez creado el .rtf y haber añadido los elementos necesarios en el contenedor, el último paso será crear la plantilla:

tipo [Elaborar Escrito] es plantilla
   -documento = [Libro].[Escrito];
   [Campos a rellenar] es seccion
      [Enlace] es variable
         -vinculo.definicion = [Libro];
         -edicion.modo = referencia;
         -edicion.valor = [&Dominio];
      [Código] es texto
         -edicion.modo = referencia;
         -edicion.valor = [Enlace]->[Datos].[Código];
      [Título] es texto
         -edicion.modo = referencia;
         -edicion.valor = [Enlace]->[Datos].[Título];
      [Autor] es texto
         -edicion.modo = referencia;
         -edicion.valor = [Enlace]->[Datos].[Autor];
      [Edición] es texto
         -edicion.modo = referencia;
         -edicion.valor = [Enlace]->[Datos].[Edición];
      [Tipo] es texto
         -edicion.modo = referencia;
         -edicion.valor = [Enlace]->[Datos].[Contenido].[Tipo];
      [Sinopsis] es texto
         -edicion.modo = referencia;
         -edicion.valor = [Enlace]->[Datos].[Contenido].[Sinopsis];
      [Libros similares] es tabla
         -edicion.modo = referencia;
         -edicion.valor = [Enlace]->[Datos].[Libros similares];
         [Nombre del libro] es texto
            -edicion.modo = referencia;
            -edicion.valor = [Enlace]->[Datos].[Libros similares].[Nombre del libro];
         [Autor del libro] es texto
            -edicion.modo = referencia;
            -edicion.valor = [Enlace]->[Datos].[Libros similares].[Autor del libro];
         [Año de publicación] es texto
            -edicion.modo = referencia;
            -edicion.valor = [Enlace]->[Datos].[Libros similares].[Año de publicación];
      fin
   fin
fin

Al referenciar la tabla Libros similares y sus tres columnas, podemos obtener los valores de las marcas <table Libros similares> y <#=Libros similares.Nombre del libro> en la elaboración del escrito. Por tanto, siempre que existan diferentes marcas que hagan alusión a las mismas tablas, columnas o campos, será suficiente con referenciarlo una sola vez en la plantilla.

El resultado que obtenemos al elaborar el escrito es el siguiente:

Creamos el objeto

Elaboramos el escrito

Y finalmente, obtenemos el escrito resultante con los resultados esperados