English

8 Configuración de la visualización de formularios

CartoDruid permite definir la visualización que se le quiere dar a un formulario, y definir reglas para determinar qué campos puede editar el usuario o qué reglas de validación aplicar.

Para poder crear un formulario de edición alfanumérica propio para una capa es necesario establecer el atributo alphaEditFinisher de la capa como sigue:

<alphaEditFinisher>userFormAlphaEditFinisher</alphaEditFinisher>

Estableciendo este parámetro, CartoDruid buscará dentro de la carpeta cartodroid/values un fichero con el nombre identificadordecapa_AlphaEdit.xml. Por ejemplo, para configurar un formulario para la capa "aforos", habrá que crear un XML cartodroid/values/aforos_AlphaEdit.xml.

Nota: el fichero se almacena en un sistema de ficheros Android que es sensible a minúsculas/mayúsculas, el nombre del fichero debe empezar con exactamente el identificador de la capa, luego si la capa se ha identificado como INSPECCIONES, el fichero debe llamarse INSPECCIONES_AlphaEdit.xml.

8.1 Estructura general del fichero

El XML de configuración del formulario tendrá la siguiente organización:

Formulario (<form>): pantalla de edición alfanumérica
Grupo de pestañas (<tabs>), y para cada pestaña anidada (<tab>):
- Grupo de campos de la pestaña (<fields>), y dentro de ésta, por cada campo a mostrar, tendremos una etiqueta <field>.

Un ejemplo de la organización del fichero XML:

<form>
 <id>aforosForm</id>
 <name>Aforos (Edición)</name> <!-- nombre a mostrar como título de pantalla -->
 <tabs class="linked-list">
 <tab>
 <id>tab1</id>
 <name>Edición</name> <!-- nombre de la pestaña -->
 <fields class="linked-list">
 <field>
 …
 </field>
 …
 </fields>
 </tab>
 …
 </tabs>
</form>

8.2 Configuración de campos del formulario

Etiqueta	Descripción
id	Identificador único del campo.
name	Nombre que se mostrará para el campo.
type	Tipo de campo, puede ser `TEXT`, `DROPDOWN`, `DATE`, `BOOLEAN`, `SEPARATOR`, `INFO`, `SIGN`. Nota: el tipo `COMBO` ha desaparecido en favor de `DROPDOWN`.
inputType	Tipo de componente del campo `TEXT`: configurable en función de http://developer.android.com/reference/android/text/InputType.html. Por ejemplo, para configurar un campo numérico, con signo y decimal, se pondría `12290` (2 + 4096 + 8192), equivalente a sumar: • `InputType.TYPE_CLASS_NUMBER` (2) • `InputType.TYPE_NUMBER_FLAG_SIGNED` (4096) • `InputType.TYPE_NUMBER_FLAG_DECIMAL` (8192) Para configurar un `textarea` se utilizaría el número `131073` (1 + 131072).
regexp	Expresión regular que debe cumplir el valor introducido por el usuario para validar correctamente. Solo aplicable a campos de tipo `TEXT`. Útil para validar valores numéricos, emails, teléfonos, etc.
hint	Texto de ayuda para rellenar el campo.
extendedHint	Texto extendido de ayuda para rellenar el campo.
persistedField	Nombre del campo de la base de datos que se utilizará para mostrar o almacenar la información.
required	Indica si el campo es obligatorio. Si está en `true`, no se guardarán los datos hasta rellenarlo. Si no se incluye, su valor por defecto es `false`.
deletable	Indica si se permite al usuario eliminar el valor del campo.
editable	Indica si el campo es editable.
defaultValue	Valor por defecto del campo: • Para campos de tipo `TEXT`: un texto • Para `DROPDOWN`: el código del combo (ej: `'VI'` para 'Viñedo') • Para `DATE`: con el formato `'dd/MM/yyyy'` • Para `BOOLEAN`: `'true'` o `'false'` (cualquier otro valor se interpreta como `false`)
choices	Permite definir una lista de `<items>` de un desplegable asociado al campo. Cada ítem contiene un `key` (código) y un `value` (descripción). Ver ejemplo más adelante.
choicesByFile	Identifica el fichero que contiene los valores del desplegable. Debe estar en la ruta `/cartodroid/values`.
choicesByQuery	Consulta SQL para cargar los valores del desplegable. Se debe indicar el fichero de base de datos con `<dbFile>` (ruta relativa o absoluta) y la consulta con `<query>`.

Ejemplos de configuración del campo inputType en función del texto a recoger:

Campo típico	Constantes usadas	Valor entero
Números
Número entero	`TYPE_CLASS_NUMBER (2)`	2
Número con signo y decimales	`TYPE_CLASS_NUMBER (2)` + `TYPE_NUMBER_FLAG_SIGNED (4096)` + `TYPE_NUMBER_FLAG_DECIMAL (8192)`	12290
Número con decimales (sin signo)	`TYPE_CLASS_NUMBER (2)` + `TYPE_NUMBER_FLAG_DECIMAL (8192)`	8194
Teléfono	`TYPE_CLASS_PHONE (3)`	3
Texto
Texto multilínea (textarea)	`TYPE_CLASS_TEXT (1)` + `TYPE_TEXT_FLAG_MULTI_LINE (131072)`	131073
Nombre propio	`TYPE_CLASS_TEXT (1)` + `TYPE_TEXT_VARIATION_PERSON_NAME (96)`	97
Email	`TYPE_CLASS_TEXT (1)` + `TYPE_TEXT_VARIATION_EMAIL_ADDRESS (32)`	33
URL	`TYPE_CLASS_TEXT (1)` + `TYPE_TEXT_VARIATION_URI (16)`	17
Dirección postal	`TYPE_CLASS_TEXT (1)` + `TYPE_TEXT_VARIATION_POSTAL_ADDRESS (112)`	113
Texto con autocorrección	`TYPE_CLASS_TEXT (1)` + `TYPE_TEXT_FLAG_AUTO_CORRECT (32768)`	32769
Texto con sugerencias desactivadas	`TYPE_CLASS_TEXT (1)` + `TYPE_TEXT_FLAG_NO_SUGGESTIONS (524288)`	524289
Códigos / IDs
Código / ID en mayúsculas	`TYPE_CLASS_TEXT (1)` + `TYPE_TEXT_FLAG_CAP_CHARACTERS (4096)` + `TYPE_TEXT_FLAG_NO_SUGGESTIONS (524288)`	528385
Contraseñas
Contraseña numérica (PIN)	`TYPE_CLASS_NUMBER (2)` + `TYPE_NUMBER_VARIATION_PASSWORD (16)`	18
Contraseña (texto)	`TYPE_CLASS_TEXT (1)` + `TYPE_TEXT_VARIATION_PASSWORD (128)`	129
Contraseña visible temporalmente	`TYPE_CLASS_TEXT (1)` + `TYPE_TEXT_VARIATION_VISIBLE_PASSWORD (144)`	145
Fecha / Hora
Campo de fecha	`TYPE_CLASS_DATETIME (4)` + `TYPE_DATETIME_VARIATION_DATE (16)`	20
Campo de hora	`TYPE_CLASS_DATETIME (4)` + `TYPE_DATETIME_VARIATION_TIME (32)`	36

Nota: Utilizando el tipo SEPARATOR es posible crear cabeceras intermedias para los datos, o bien vacías (una línea horizontal), o bien con un texto (rellenando el atributo name).

8.2.1 Definición de pestañas en el formulario

El siguiente trozo de código define tres pestañas vacías, el usuario podrá moverse de una a otra desplazando lateralmente la pantalla.

<form>
 <id>dopfigurasForm</id>
 <name>Inspecciones DOP/IGP</name>
 <tabs class="linked-list">
 <tab>
 <id>general</id>
 <name>1.- General</name>
 </tab>
 <tab>
 <id>obligatorios</id>
 <name>2.- Obligatorios</name>
 </tab>
 <tab>
 <id>facultativos</id>
 <name>3.- Facultativos</name>
 </tab>
 </tabs>
</form>

Formulario con tres pestañas

8.2.2 Uso de campos booleanos

Con el siguiente trozo de XML, configuramos un apartado con tres capos booleanos para un formulario de inspecciones. Para mostrar un control de tipo booleano el campo de la tabla debe empezar por "B_", ver el apartado de 9.2 - Nomenclatura de los nombres de campos de las tablas.

<field>
 <id>obl_separador2</id>
 <name>Nombre registrado</name>
 <type>SEPARATOR</type>
</field>
<field>
 <id>b_oblig_nombre_aparece</id>
 <name>Aparece en el etiquetado</name>
 <hint>El nombre de la DOP/IGP debe aparecer en el etiquetado.</hint>
 <type>BOOLEAN</type>
 <persistedField>b_oblig_nombre_aparece</persistedField>
 <editable>true</editable>
</field>
<field>
 <id>b_oblig_nombre_logo_ue</id>
 <name>Nombre registrado junto a logo UE</name>
 <hint>El nombre de la DOP/IGP está en el mismo campo visual que el símbolo de la Unión.</hint>
 <type>BOOLEAN</type>
 <persistedField>b_oblig_nombre_logo_ue</persistedField>
 <editable>true</editable>
</field>
<field>
 <id>b_oblig_nombre_mencion_igp</id>
 <name>Va acompañado de mención DOP/IGP</name>
 <type>BOOLEAN</type>
 <persistedField>b_oblig_nombre_mencion_igp</persistedField>
 <editable>true</editable>
</field>

Uso de separador y componentes booleanos

8.2.3 Validación de datos con expresión regular

El siguiente código muestra cómo definir una validación de un campo de correo electrónico:

<field>
 <id>d_info_correo</id>
 <name>Correo Electronico</name>
 <hint></hint>
 <type>TEXT</type>
 <persistedField>d_info_correo</persistedField>
 <editable>true</editable>
 <regexp>^[_A-Za-z0-9-\+]+(\.[_A-Za-z0-9-]+)*@[A-Za-z0-9-]+(\.[A-Za-z0-9]+)*(\.[A-Za-z]{2,})$</regexp>
</field>

Si el usuario no introduce un valor válido, se mostrará un mensaje de error en el formulario.

Mensaje de error tras validación de formulario

Otros ejemplos de expresiones regulares que pueden ser de utilidad:

Introducir un valor numérico de 2 decimales permitiendo separador de "." o ",":

  <regexp>\d+([\.,]\d{1,2})?</regexp>

Validación básica de DNI (solo formato no código de control):

  <regexp>[0-9]{7,8}[a-zA-Z]</regexp>

Validar la entrada para permitir solo values numéricos 1, 2 o 3.

  <field>
    <id>d_tipo_instalacion</id>
    <name>Tipo instalacion</name>
    <hint></hint>
    <type>TEXT</type>
    <inputType>2</inputType>
    <persistedField>d_tipo_instalacion</persistedField>
    <editable>true</editable>
    <regexp>(1|2|3)</regexp>
  </field>

Para más información sobre expresiones regulares: https://docs.oracle.com/javase/tutorial/essential/regex/

8.2.4 Uso de desplegables en formularios

Cartodruid permite definir desplegables en formularios de tres formas diferentes:

1) Incluyendo directamente en el fichero de configuración del formulario los valores a utilizar.

2) Utilizando los valores definidos en un fichero de propiedades.

3) Cargando los valores desde una tabla de Base de Datos.

En primer lugar, hemos definido el campo en el fichero xml de configuración del formulario, para ello indicando que es de tipo DROPDOWN.

<field>
 <id>variedad</id>
 <name>Variedad</name>
 <type>DROPDOWN</type>
 <persistedField>c_variedad</persistedField>
 <editable>true</editable>
 …
</field>

Para cargar el contenido del desplegable tenemos tres opciones que se configurarán con un atributo dentro de <field></field>.

Valores directamente en el fichero de configuración del formulario

En este caso, dentro de la configuración del campo, añadimos el listado de opciones de la siguiente forma:

<field>
 <id>variedad</id>
 <name>Variedad</name>
 <type>DROPDOWN</type>
 <persistedField>variedad</persistedField>
 <editable>true</editable>
 <deletable>true</deletable>
 <choices>
 <item>
 <key>CA</key>
 <value>Cabernet</value>
 </item>
 <item>
 <key>GA</key>
 <value>Garnacha</value>
 </item>
 <item>
 <key>ME</key>
 <value>Merlot</value>
 </item>
 …
 </choices>
</field>

Cada <item> se corresponde con una de las opciones del desplegable. El valor de la etiqueta <key> es lo que se guardará en base de datos y el de <value> lo que aparecerá en el desplegable.

Mediante un fichero de propiedades

En este caso, utilizamos la etiqueta <choicesByFile>variedades.properties</choicesByFile>, donde variedades.properties es el nombre del fichero que contiene las diferentes opciones que se cargarán en el desplegable.

<field>
…
<choicesByFile>variedades.properties</choicesByFile>,
</field>

Dicho fichero debe estar en la carpeta cartodroid/values y su estructura debe ser la siguiente

CA=Cabernet
GA=Carnacha
ME=Merlot
PA=Palomino
SA=Sauvignon Blanc
TE=Tempranillo
VE=Verdejo
VI=Viura

CA es el valor que se almacenará en base de datos y Cabernet el contenido que aparecerá en el desplegable.

A partir de base de datos

En el tercer caso, se debe indicar en el fichero de configuración del formulario una consulta SQL y la base de datos sobre la que ejecutarla:

<field>
…
 <choicesByQuery>
 <dbFile>plantaciones.sqlite</dbFile>
 <query>Select id, nombre from variedades</query>
 </choicesByQuery>
</field>

En este caso, la base de datos es la misma que contiene las capas del proyecto, pero podría ser cualquier otra y no es necesario que sea una capa gráfica, basta con que sea una tabla alfanumérica. La ruta al fichero de base de datos puede ser relativa, y se buscará la BD en la carpeta /cartodroid/data o absoluta.

En la consulta, el primer valor se utilizará como clave (lo que se almacenará en la base de datos) y el segundo es el texto que aparecerá en el desplegable.

8.2.5 Uso de campos de firma

Con el siguiente trozo de XML, configuramos un campo de firma en el que se queda registrada la firma que dibujemos en una pantalla emergente. En el bloque que aparece en el formulario podemos definir el título (name), un texto de aclaración (hint), así como exigir que la firma sea realizada obligatoriamente (required). Nos aparecerá un botón para indicar que queremos firmar y la firma en pequeño en caso de que ya se haya firmado. Para mostrar un control de tipo firma el campo de la tabla debe empezar por "S_", ver el apartado de 9.2 - Nomenclatura de los nombres de campos de las tablas.

<field>
 <id>S_FIRMA_TITULAR</id>
 <name>Firma</name>
 <hint>Antes de iniciarse la actuación he sido informado sobre la forma en que se va a desarrollar la misma.</hint>
 <type>SIGN</type>
 <required>true</required>
 <persistedField>S_FIRMA_ TITULAR</persistedField>
</field>