The (COLL) collection is the most important node of the mappings.xml file and in a simple way we could define a collection as a view of data corresponding to a table or to a Database query which in turns, logically, can link with another tables or queries.

Obviously, the above is a simple description of this node, in which not only the displaying on screen are defined, but also, the type of data corresponding in the DB are defined, the relations with another tables, the business rules affecting the collection, the filtering ways, behaviours… etc.

The machinery provided by CGSOFT is in charge to transfor the definition of the mappings.xml file collections in the form of objects collections, so that we do not work directly with a DB and we can completely abstract from storage.

A collection can be displayed in several ways :

1. Like aGrid (listing).
   
2. Like a Form, when we are entering data.
3. Like a Tree.
4. Like a Calendar.
5. Like a Graphic (for certain apps).

Here, we can see a screenshot of a collection when we are on data entering mode:

As we can see, a collection on data insertion mode corresponds with a form, which can be divided into tabs for a better organization of the different data to fulfill.

<collprops type="general">
<coll name="ParteDiario" ... sql="SELECT ..." objname="Documentos" updateobj="Documentos" progid="ASData.CASBasicDataObj" ...>
 
       <!-- GRUPOS O PESTAÑAS EN QUE VOY A DIVIDIR LA COLECCION -->
       <group name="Ficha" id="1"></group>
       ...
 
        <!-- PROPIEDADES DE ENLACE CON OTRAS COLECCIONES -->
	<prop name="IDSERIE" group="1" visible="0" type="N" mapcol="Series" mapfld="ID" keep="true"></prop>
        ....
 
	<!-- GRUPO 1 (dejar incluso este comentario para separar los props de los distintos grupos)-->
	<prop name="FECHA" visible="7" group="1" labelwidth="8" type="D" fieldsize="8" size="10">FECHA</prop>
        ....
 
	<!-- GRUPO 2 -->
	<prop name="MAP_ETQ1" group="2" visible="1" labelwidth="20" type="TL" fieldsize="25" bgcolor="#008030" forecolor="#FFFFFF">Recursos Propios</prop>
        ...
 
	<!-- CAMPOS NO VISIBLES PERO NECESARIOS -->
	<prop name="MAP_SIMTIPO" visible="0" group="1" type="T" fieldsize="4" size="4" linkedto="IDTIPODOC" linkedfield="SIMBOLO"></prop>
	...
 
        <!-- REGLAS DE NEGOCIO -->
	<create>
		<action name="setval" field="FECHA" value="##NOW##"></action>				
	</create>
        ...
        ...
        <!-- FIN DE LAS REGLAS DE NEGOCIO  -->
 
	<!-- NODO PARA GESTIONAR LOS FILTROS DE BUSQUEDA -->
	<asfilter fontsize="8" left="12" sort="false">
		<field name="NUMCOMPLETO" fldname="NUMCOMPLETO" oper="##FLD## LIKE '##VAL##%'" width="15" tooltip="Albaran" newline="false">ALBARAN</field>
                ...
	</asfilter>
</coll>
</collprops>

The mantadory attibutes in the <COLL> node are:

1. name
2. sql
3. objname
4. updateobj
5. progid.

This attribute assigns a name to the collection.

Every collection must have a unique name to be able to refer to it.

It cannot be two collections with the same name inside the same app in execution for the same type of user.

If there were two collection names repeated, the last one defined in the XML would be taken.

This attribute contains an SQL sentence that will be used to read the collection data, any field that is going to appear on the screen or that needs to take value to be used later, must be rescued in the SQL.

Several tables can be combined through connections but not through field equalities, since the SQL sentence shouldn´t have WHERE clauses (using the filter attribute to specify the WHERE).

The tables name can be preceded by a prefix that will be replaced by the access data controls.

This allows to have tables corresponding to several apps inside the same database. In case the SQL has WHERE clauses those ones should be included into a sub-query (filter attribute) or in any similar structure to prevent that the machinery make up sentences that are syntactically incorrects.

<coll name="ParteDiario" title="el parte diario" forprint="false" sql-debug="true" 
	sql="SELECT d.ID,d.IDSERIE,d.IDEMPRESA,d.IDTIPODOC,d.IDMONEDA,d.IDUSUARIO,d.IDOBRA,
	d.FECHA,d.NOMCLIENTE,d.DIRCLIENTE,d.PERSCONTACTO,d.OBSERV,d.FOTO,d.FIRMA1,
	d.FIRMA2,d.NUMERO,d.OPTIONS,
	s.SERIE AS MAP_SERIE,
	td.SIMBOLO AS MAP_SIMTIPO,
	o.CODIGO AS MAP_CODIGO,o.NOMBRE AS MAP_OBRA
	FROM ((((##PREF##Documentos d
	LEFT OUTER JOIN ##PREF##TiposDocumento td ON d.IDTIPODOC=td.ID)
	LEFT OUTER JOIN ##PREF##Empresa e ON d.IDEMPRESA=e.ID)
	LEFT OUTER JOIN ##PREF##Series s ON d.IDSERIE=s.ID)
	LEFT OUTER JOIN ##PREF##Obras o ON d.IDOBRA=o.ID)" 
	 objname="Documentos" updateobj="Documentos" progid="ASData.CASBasicDataObj" editwidth="66" editheight="69" filter="MAP_SIMTIPO='PD'">

The previous example defines a collection which SQL instruction selects the data from the Documents table.

The ##PREF## prefix will be replaced by the app when when we are going to perform data operations.

In case the app has not define any prefix, the ##PREF## reserved word will be deleted from the SQL instruction, so it will not cause any error.

In case a prefix is being used, this one will be placed in the place of ##PREF##.

For instance, if it is indicated to the data app that the prefix to be used is “App”, the previous instruction will be as follows:

	FROM ((((App_Documentos d
	LEFT OUTER JOIN App_TiposDocumento td ON d.IDTIPODOC=td.ID)
	LEFT OUTER JOIN App_Empresa e ON d.IDEMPRESA=e.ID)
	LEFT OUTER JOIN App_Series s ON d.IDSERIE=s.ID)
	LEFT OUTER JOIN App_Obras o ON d.IDOBRA=o.ID)

This attribute contains the object name of the main data object in the SQL sentence that is used to read the database data. In the previous example, the name of the main object will be without doubt the “Documents” table, but but this is not always so obvious. In case of a union of several tables, objname must be that table from which the other tables of the SELECT instruction depend on.

This attribute is used to indicate to the objects which one is the table used to write in the databas. In general, this attribute matchs with objname in a 99,9% of the times, but this is does not have to be like this.

For instance, objname can be a name of a query in the database, which has several joined tables, so they cannot be used to write.
IMPORTANT: The objname has to be a table COMPULSORILY, since it will be used to write data.

This attribute is used to tell the collection which type are the object it manages, CGSOFT provides a certain number of libraries which make that the collection has some predefined behaviours:

*  **ASData.CASBasicDataObj**: It has the basic behaviours of a collection. If we don´t want to make any special control, this is the kind all the collection created in our mappings must use. 
*  **ASGestion.CASUser**: It has behaviours related to the users control. 

This attribute indicates the collection a condition that must apply to the logs selected through the instruction specified in the “sql” attribute. IT IS NOT necessary to write the “WHERE” word. It may be interpreted as the WHERE part of the SQL sentence..

The data filter is placed separately from the rest of the SQL sentence because during the data selection other filters can be added and they will be added to this one. This field is optional.In case not to put any value on it, all the query logs will be selected, unless there is another selecting criterion embedded inside the SQL sentence (this is done a lot in the complex listing) The data filter allows the use of the ##ENTID## macro (or another similar ones). During the app execution, these macros will be replaced by the values managed in each case. In the case of the ##ENTID## macro, and that there is no active company, or that the data app doesn´t work with companies, this macro is replaced by NULL. The replacement is made in an smart way, as well as a filter of the IDEMPRESA=##ENTID## type, with a non-existent company or without working with companies, it will be replaced by “IDEMPRESA IS NULL”.

This attribute allows to arrange the data of a collection by the fields the programmer wants to. IT IS NOT necessary to put the words “ORDER BY”. By default, the collections don´t have any order, nevertheless it should be desirable that the data will be shown with an order by default when showing on the display. The filters app later during the execution of the program will change the value of the ordering of the collection, however, each time the program is started, the ordering will be initiated with this value.

The sort attribute may have like a value a list of fields separated by commas in the same way that the ORDER BY sentence uses in a SELECT instruction. The fields can be followed by the DESC or ASC attributes to indicate ascending or descending order (this last one it is not necessary to specify it explicitly, being this one that is recognized by default).

It decides if the data of that collection are going to be refreshed when it is returned from a window, but only if any change occurred in that window.
If this attribute is not defined its value by default is false.

This attribute, which is defined at the collection level, indicates whether or not to fill the grid with the data of the collection where it is defined.
It takes the true or false values, by default the true value is taken.
This attribute is interpreted in the Frame.

This attribute, available in Android, causes that in the contents and in the collections the data can be refreshed by pulling from the top of the list.

In order to optimize loading times of the app, if we have a collection with a large number of tabs, we can do that do not pre-load in the memory all of them from a beginning and thus limit the number of tabs in memory and the times of painted of the screen. we can do that they do not precarguen in memory all from a beginning and limit like this the number of tabs in memory and the screen painted times.

For this, the page-limit-off attribute has been implemented to a collection level, by default, if nothing is specified, page-limit-off=“6”.

It gets activated with the group-theme=“material” attribute to a collection level.

It can be of two types fix or scroleable:

1. Fix it means that it will put all the tabs across the width of the screen so that you do not have to scroll with the attribute. Through the tab-mode=“fixed” attribute.
2. Scroleable It means that it will design the tabs according to what occupies its title, one next to the other one, and if they do not fit on the screen the scroll will be enabled. Through the tab-mode=“scrollable” attribute.

Pedro Santos Pantoja psantos@cgsoft.es