Colecciones

¿Qué es una colección?

Una colección es un componente de ODL que se define a nivel de contenedores, tanto en definiciones de tipo, como en definiciones de sistema. Permiten almacenar objetos de igual o distinto tipo, y para cada definición de colección que exista se generará una tabla en la base de datos. Además, es posible definir varias colecciones en una misma definición de contenedor.

Es un componente importante, ya que para poder crear objetos o acceder a ellos, es necesario que su definición esté incluída en al menos una colección. Al entrar en una colección, podremos acceder a los objetos almacenados, así como crear objetos del tipo o tipos que estén contenidos en la definición de colección.

Siempre que definamos una colección en un contenedor, no podremos declararla como una definición de tipo, sino que tendremos que definirla como una instancia. Podremos declarar un tipo de colección, pero nunca en un contenedor. Esto nos serviría para declarar nuevas definiciones a partir de la colección de tipo.

Como hemos dicho, la definición de una colección genera una tabla en la base de datos. Para su creación, será necesario indicar el nombre de la tabla. Esto lo hacemos utilizando el atributo nombre_tabla, que acepta una ristra como valor. El nombre de la tabla tendrá que estar siempre precedido del prefijo TC$:

[Definición] es contenedor
    [Contenido] es coleccion     //Declaración como instancia. Se creará la colección.
        -nombre_tabla = "TC$NOMBRE";
        ...
        ...
        ...
    fin
fin

tipo [Definición] es coleccion     //Declaración como tipo, fuera de la definición de un contenedor. No se crea ninguna colección.
    -nombre_tabla = "TC$NAME";     //Se utilizará para definir otras colecciones.
    ...
    ...
    ...
fin 

Declaraciones de contenido

A la hora de definir una colección, es necesario declarar el contenido que tendrá la colección. Es decir, se especificarán todas las definiciones de contenedor correspondientes a los tipos objetos que queramos almacenar en la colección.

Para ello, utilizaremos la palabra reservada contiene, de manera que incluiremos un contiene por cada definición de contenedor.

Su sintaxis sería la siguiente:

...
contiene [Definición de contenedor]
...

Declaraciones de columna

Como hemos dicho, una colección genera una tabla en la base de datos del centro, pero también habrá que especificar las columnas que se crearán en ella.

Con la palabra reservada columna seguida de un nombre, detallaremos dichas columnas. El nombre especificado hará referencia al título de la columna a nivel de egExplorer, no de la base de datos. Para especificar el nombre de la columna en la base de datos utilizaremos el atributo columna_bd.nombre. Ambos nombres no tienen por qué coincidir, el nombre de la columna en la tabla puede ser distinto al del listado en el egExplorer.

Además, también es necesario indicar el campo que almacenará cada una de las columnas. El atributo origen nos permite asignarle una expresión que especifique la definición de un campo, que tendrá que estar incluído en la definición de contenedor que contenga la colección.

...
columna [Nombre de la columna]
    -columna_bd.nombre = "NOMBRE";
    -origen = [Formulario].[Campo];
...

NOTA: En caso de que la colección contenga objetos de distinto tipo, los campos que se especifiquen en las columnas con el atributo origen tendrán que estar definidos en los contenedores. Es decir, la ruta tendrá que ser exactamente igual en todas las definiciones de contenedor.

Sintaxis y ejemplo

Una vez sabemos los elementos necesarios que hay que incluir para una correcta definición de colección, veamos una sintaxis completa utilizando un ejemplo concreto.

Partimos de una definición de tipo contenedor llamada Expediente. Por tanto, crearemos una colección que almacene objetos de ese tipo:

tipo [Expediente] es contenedor
    [Datos generales] es formulario
        [Nº de expediente] es timbre
            -certificado.valor = [&Valor_secuencia];
            -certificado.secuencia.nombre = "STR$EXPEDIENTE"; 
            -certificado.secuencia.longitud = 5; 
        [Fecha de alta] es fecha
        [Tipo de solicitud] es texto
            -edicion.seleccion = verdadero;
            -edicion.valores = $matriz("Solicitud_1","Solicitud_2","Solicitud_3");
            -edicion.desplegable = verdadero;
   fin
fin

[Expedientes] es contenedor
    [Contenido] es coleccion
        -nombre_tabla = "TC$EXPEDIENTES";

        contiene [Expediente]   //Esta colección almacenará objetos de tipo Expediente

        columna [Número de expediente]
            -columna_bd.nombre = "NUMERO_EXPEDIENTE";
            -origen = [Datos generales].[Nº expediente];

        columna [Fecha de creación]
            -columna_bd.nombre = "FECHA";
            -origen = [Datos generales].[Fecha de alta];

        columna [Tipo de solicitud]
            -columna_bd.nombre = "TIPO_SOLICITUD";
            -origen = [Datos generales].[Tipo de solicitud];
    fin
fin

Para poder acceder a la colección, será necesario ubicar la instancia de contenedor donde está incluída la colección en una habitación:

[Oficina] es habitacion
    ubicado [Expedientes] 
        -lugar = "Estantes";
fin

Veamos el resultado en la aplicación de administración egExplorer:

Para acceder a la colección es necesario acceder a la instancia Expedientes. Al acceder, se nos abrirá directamente la colección. Vemos en la parte superior, que aparece la pestaña Contenido haciendo referencia a nuestra colección. En caso de haber definido más colecciones en Expedientes, aparecería una pestaña por cada una de ellas.

Vemos también que los nombres de las columnas se corresponden con los declarados en el código. Además en la parte superior derecha, aparece un botón llamado Nuevo contenedor que al picar en él, nos permitirá crear un objeto de aquellas definiciones de contenedor que estén incluídas en la colección. En este caso, sólo podríamos crear un objeto de tipo Expediente.

Atributos

A lo largo del artículo, hemos ido conociendo algunos de los atributos que intervienen en la definición de una colección, sobre todo, aquellos que son estrictamente necesarios.

No obstante, existen algunos atributos más, tanto para la definición de colección, como para las declaraciones de contenido y columnas. Veámos cuáles son:

Atributos genéricos de la definición de un componente

Atributo	Tipo	Valor por defecto	Observaciones
ayuda	Texto		Marcador en la ayuda del centro.
descripcion	Texto	[Nombre]	Comentario sobre el componente.
etiqueta	Texto	[Nombre]	Etiqueta del componente.
orden	Entero	0	Indica la prioridad del componente al ordenarlo sobre el recurso.
visible	Lógico	Verdadero	Indica si el componente es visible.

Atributos de la definición de colección

Atributo	Tipo	Valor por defecto	Observaciones
nombre_tabla	Texto		Nombre de la tabla que se creará para la colección en la base de datos. Deberá incluir el prefijo TC$.

Atributos de la declaración de contenido

Atributo	Tipo	Valor por defecto	Observaciones
minimo	Entero	0	Número mínimo de objetos que se podrán crear en la colección. En caso de borrar objetos de la colección, siempre tendrán que existir al menos el número mínimo indicado.
maximo	Entero	Sin límite	Número máximo de objetos que se podrán almacenar en la colección.

Atributos de la declaración de columna

Atributo	Tipo	Valor por defecto	Observaciones
columna_bd.nombre	Texto		Nombre de la columna en la base de datos.
columna_bd.tipo	Texto		En caso de tener una expresión en el atributo origen, se especificará el tipo de la columna. Necesario para los campos código y vínculo.
columna_bd.longitud	Entero	50	En caso de tener una expresión en el atributo origen, se especificará la longitud del valor obtenido por la expresión. Por ejemplo, una cadena de caracteres.
columna_bd.precision	Entero	4	En caso de obtener un valor de tipo moneda o real en la expresión del atributo origen, limitará la parte decimal a la precisión indicada.
origen	Expresión		Expresión cuyo resultado almacenará en la columna.
visible	Lógico	Verdadero	Indica si la columna es visible.

Aumentando la complejidad

Siguiendo con el ejemplo del apartado 2 de este artículo, vamos a aumentar un poco la complejidad del mismo, para abordar algún caso más en el uso de las colecciones que pueden ser de utilidad a la hora de desarrollar nuestro sistema de información.

En el ejemplo, simplemente definimos una colección Expedientes en la que se almacenan los objetos de tipo Expediente, pero, imaginemos ahora, que por cada Expediente que se crea pueden existir varias entradas y salidas de información. Como ya sabemos, es necesario crear alguna colección donde almacenar dichas Entradas y Salidas, pero, en este caso, no crearemos una colección para todas las Entradas y otra para las Salidas, sino que definiremos una colección en la definición de tipo Expediente. Esto provocará que cada vez que se cree un objeto de tipo Expediente, se incluirá en él una colección que almacenará sólamente las Entradas y Salidas que se creen desde esa colección. Por tanto, al acceder a un objeto de tipo Expediente, existirá una colección en la cual podremos ver el listado de las Entradas y Salidas asociadas a ese Expediente.

Veamos la definición de Entrada y Salida, además de la inclusión de la definición de colección en la definición de Expediente:

tipo [Entrada] es contenedor
    [Datos generales] es formulario
        [Número] es timbre
            -certificado.subsecuencia.valor = $Copiartexto($texto($Año($Hoy)), 3, 2);
            -certificado.valor = [&Valor_subsecuencia] + "/" + [&Valor_secuencia];
            -certificado.secuencia.nombre = "STR$ENTRADA";
            -certificado.secuencia.longitud = 4;
        [Fecha] es fecha
            -edicion.modo = copia;
            -edicion.valor = [Número].[&Fecha];
        [Remitente] es texto
        [Destinatario] es texto
    fin
fin

tipo [Salida] es contenedor
    [Datos generales] es formulario
        [Número] es timbre
            -certificado.subsecuencia.valor = $Copiartexto($texto($Año($Hoy)), 3, 2);
            -certificado.valor = [&Valor_subsecuencia] + "/" + [&Valor_secuencia];
            -certificado.secuencia.nombre = "STR$SALIDA";
            -certificado.secuencia.longitud = 4;
        [Fecha] es fecha
            -edicion.modo = copia;
            -edicion.valor = [Número].[&Fecha];
        [Remitente] es texto
        [Destinatario] es texto
    fin
fin

tipo [Expediente] es contenedor
    [Datos generales] es formulario
        [Nº de expediente] es timbre
            -certificado.valor = [&Valor_secuencia];
            -certificado.secuencia.nombre = "STR$EXPEDIENTE"; 
            -certificado.secuencia.longitud = 5; 
        [Fecha de alta] es fecha
        [Tipo de solicitud] es texto
            -edicion.seleccion = verdadero;
            -edicion.valores = $matriz("Solicitud_1","Solicitud_2","Solicitud_3");
            -edicion.desplegable = verdadero;
   fin

   [Contenido] es coleccion
       -nombre_tabla = "TC$DOCUMENTOS"

       contiene [Entrada]

       contiene [Salida]

       columna [Nombre]
           -columna_bd.nombre = "NOMBRE";
           -origen = [&Nombre];    //Propiedad [&Nombre] de la definición de contenedor

       columna [Fecha]
           -columna_bd.nombre = "FECHA";
           -origen = [Datos generales].[Fecha];

    fin
fin

• Primero creamos un objeto de tipo Expediente y accedemos a él desde la colección Expedientes. Vemos que aparece una etiqueta llamada Contenido para acceder a la colección del objeto.

• Una vez en la colección del objeto, vemos que picando en el botón "Nuevo contenedor" podremos crear objetos de tipo Entrada y Salida...

• ...Y que una vez generados, podremos visualizar en la colección del propio objeto.