Español

8 Configuration of form display

CartoDruid allows defining the visualization you want to give to a form, and defining rules to determine what fields the user can edit or what validation rules to apply.

To create a custom alphanumeric editing form for a layer, it is necessary to set the alphaEditFinisher attribute of the layer as follows:

<alphaEditFinisher>userFormAlphaEditFinisher</alphaEditFinisher>

By setting this parameter, CartoDruid will search within the cartodroid/values folder for a file with the name layeridentifier_AlphaEdit.xml. For example, to configure a form for the "aforos" layer, you will need to create an XML cartodroid/values/aforos_AlphaEdit.xml.

Note: the file is stored in an Android file system that is case-sensitive, the file name must start with exactly the layer identifier, so if the layer has been identified as INSPECCIONES, the file must be called INSPECCIONES_AlphaEdit.xml.

8.1 General structure of the file

The form configuration XML will have the following organization:

Form (<form>): alphanumeric editing screen
Tab group (<tabs>), and for each nested tab (<tab>):
- Tab field group (<fields>), and within this, for each field to display, we will have a <field> tag.

An example of the organization of the XML file:

<form>
 <id>aforosForm</id>
 <name>Aforos (Edición)</name> <!-- name to display as screen title -->
 <tabs class="linked-list">
 <tab>
 <id>tab1</id>
 <name>Edición</name> <!-- tab name -->
 <fields class="linked-list">
 <field>
 …
 </field>
 …
 </fields>
 </tab>
 …
 </tabs>
</form>

8.2 Form field configuration

Tag	Description
id	Unique field identifier.
name	Name that will be displayed for the field.
type	Field type, can be `TEXT`, `DROPDOWN`, `DATE`, `BOOLEAN`, `SEPARATOR`, `INFO`, `SIGN`. Note: the `COMBO` type has disappeared in favor of `DROPDOWN`.
inputType	Type of TEXT field component: configurable according to http://developer.android.com/reference/android/text/InputType.html. For example, to configure a numeric field with sign and decimal, use `12290` (2 + 4096 + 8192), equivalent to adding: • `InputType.TYPE_CLASS_NUMBER` (2) • `InputType.TYPE_NUMBER_FLAG_SIGNED` (4096) • `InputType.TYPE_NUMBER_FLAG_DECIMAL` (8192) To configure a `textarea`, use the number `131073` (1 + 131072).
regexp	Regular expression that the value entered by the user must meet to validate correctly. Only for `TEXT` fields. Useful to validate numeric values, emails, phone numbers, etc.
hint	Help text to fill in the field.
extendedHint	Extended help text to fill in the field.
persistedField	Name of the DB field that will be used to display/store the information.
required	Indicates if the field is mandatory. If true, data won’t save until it’s filled. Defaults to false if omitted.
deletable	Indicates if the user is allowed to delete the field value.
editable	Indicates if the field is editable.
defaultValue	Default value of the field: • For `TEXT` fields: a text value • For `DROPDOWN` fields: the combo code (e.g. `'VI'` for 'Viñedo') • For `DATE` fields: format `'dd/MM/yyyy'` • For `BOOLEAN` fields: `'true'` or `'false'` (any other value = `false`)
choices	Defines a list of `<items>` for a dropdown. Each item has a `key` (code) and `value` (description). See example in docs.
choicesByFile	Identifies the file containing the dropdown values. File should be in `/cartodroid/values`.
choicesByQuery	SQL query to load dropdown values. Specify the DB file with `<dbFile>` (relative or absolute path) and the query with `<query>`.

Examples of configuring the inputType field depending on the text to collect:

Typical field	Constants used	Integer value
Numbers
Integer number	`TYPE_CLASS_NUMBER (2)`	2
Signed decimal number	`TYPE_CLASS_NUMBER (2)` + `TYPE_NUMBER_FLAG_SIGNED (4096)` + `TYPE_NUMBER_FLAG_DECIMAL (8192)`	12290
Decimal number (unsigned)	`TYPE_CLASS_NUMBER (2)` + `TYPE_NUMBER_FLAG_DECIMAL (8192)`	8194
Phone	`TYPE_CLASS_PHONE (3)`	3
Text
Multiline text (textarea)	`TYPE_CLASS_TEXT (1)` + `TYPE_TEXT_FLAG_MULTI_LINE (131072)`	131073
Person name	`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
Postal address	`TYPE_CLASS_TEXT (1)` + `TYPE_TEXT_VARIATION_POSTAL_ADDRESS (112)`	113
Text with autocorrect	`TYPE_CLASS_TEXT (1)` + `TYPE_TEXT_FLAG_AUTO_CORRECT (32768)`	32769
Text with suggestions disabled	`TYPE_CLASS_TEXT (1)` + `TYPE_TEXT_FLAG_NO_SUGGESTIONS (524288)`	524289
Codes / IDs
Code / ID in uppercase	`TYPE_CLASS_TEXT (1)` + `TYPE_TEXT_FLAG_CAP_CHARACTERS (4096)` + `TYPE_TEXT_FLAG_NO_SUGGESTIONS (524288)`	528385
Passwords
Numeric password (PIN)	`TYPE_CLASS_NUMBER (2)` + `TYPE_NUMBER_VARIATION_PASSWORD (16)`	18
Password (text)	`TYPE_CLASS_TEXT (1)` + `TYPE_TEXT_VARIATION_PASSWORD (128)`	129
Visible password (temporarily)	`TYPE_CLASS_TEXT (1)` + `TYPE_TEXT_VARIATION_VISIBLE_PASSWORD (144)`	145
Date / Time
Date field	`TYPE_CLASS_DATETIME (4)` + `TYPE_DATETIME_VARIATION_DATE (16)`	20
Time field	`TYPE_CLASS_DATETIME (4)` + `TYPE_DATETIME_VARIATION_TIME (32)`	36

Note: Using the SEPARATOR type, it is possible to create intermediate headers for the data, either empty (a horizontal line), or with text (filling in the name attribute).

8.2.1 Definition of tabs in the form

The following code snippet defines three empty tabs, the user can move from one to another by swiping sideways on the screen.

<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>

Form with three tabs

8.2.2 Use of boolean fields

With the following XML snippet, we configure a section with three boolean fields for an inspection form. To display a boolean control, the table field must start with "B_", see section 9.2 - Nomenclature of Table Field Names.

<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>

Use of separator and boolean components

8.2.3 Data validation with regular expression

The following code shows how to define a validation for an email field:

<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>

If the user does not enter a valid value, an error message will be displayed in the form.

Error message after form validation

Other examples of regular expressions that may be useful:

Enter a numerical value with 2 decimals allowing a separator of "." or ",":

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

Basic validation of DNI (only format not control code):

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

Validate the input to allow only numeric values 1, 2 or 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>

For more information on regular expressions: https://docs.oracle.com/javase/tutorial/essential/regex/

8.2.4 Using dropdowns in forms

CartoDruid allows defining dropdowns in forms in three different ways:

1) Directly including the values to use in the form configuration file.

2) Using values defined in a properties file.

3) Loading values from a Database table.

First, we need to define the field in the XML configuration file of the form, indicating that it is of type DROPDOWN.

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

To load the dropdown content, we have three options that can be configured with an attribute within <field></field>.

Values directly in the form configuration file

In this case, within the field configuration, we add the list of options as follows:

<field>
 <id>variedad</id>
 <name>Variety</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>

Each <item> corresponds to one of the dropdown options. The value of the <key> tag is what will be saved in the database, and the <value> is what will appear in the dropdown.

Using a properties file

In this case, we use the tag <choicesByFile>varieties.properties</choicesByFile>, where varieties.properties is the name of the file that contains the different options to be loaded into the dropdown.

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

This file must be in the cartodroid/values folder and its structure should be as follows:

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

CA is the value that will be stored in the database and Cabernet is the content that will appear in the dropdown.

From a database

In the third case, you need to specify an SQL query and the database on which to execute it in the form configuration file:

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

In this case, the database is the same one that contains the project layers, but it could be any other and it doesn't need to be a graphic layer, it just needs to be an alphanumeric table. The path to the database file can be relative (and the DB will be searched in the /cartodroid/data folder) or absolute.

In the query, the first value will be used as a key (what will be stored in the database) and the second is the text that will appear in the dropdown.

8.2.5 Using signature fields

With the following XML snippet, we configure a signature field where a signature drawn on a pop-up screen is recorded. In the block that appears in the form, we can define the title (name), an explanatory text (hint), as well as require that the signature be made mandatory (required). A button will appear to indicate that we want to sign, and a small signature will be displayed if it has already been signed. To show a signature type control, the table field must start with "S_", see section 9.2 - Nomenclature of Table Field Names.

<field>
 <id>S_FIRMA_TITULAR</id>
 <name>Signature</name>
 <hint>Before the action begins, I have been informed about how it will be carried out.</hint>
 <type>SIGN</type>
 <required>true</required>
 <persistedField>S_FIRMA_ TITULAR</persistedField>
</field>