Viafirma Documents

Uso de formularios

El sistema permite crear formularios para ser usados como entrada de datos desde el backend, una aplicación de terceros o el propio dispositivo móvil.

El formulario se define en formato JSON, y en esencia, contendrá tantas variables de datos como se hayan definido en su plantilla asociada.

Formulario Base

Para construir un Formulario Base asociado a una plantilla seguiremos los siguientes pasos:

  1. Partimos de una plantilla registrada en el sistema.
  2. Generamos desde el backend el formulario asociado a la plantilla.

Main image

Con esto, ya tendremos un FORMULARIO BASE en formato JSON asociado a nuestra plantilla, lista para ser usada.

Un formulario base mostrará cada variable como tipo de elemento texto, sin ningún tipo de validaciones o diseños.

Main image

Para dotar al formulario de validaciones, formato enriquecido con distintos elementos html y obtener un Formulario Avanzado, tendremos dos opciones:

Diseñador de Formularios

Para hacer uso de todas las posibilidades descritas para los formularios avanzados, se recomienda el uso de la herramienta JForm Designer, de viafirma.

En el siguiente link se podrá hacer uso de la herramienta.

http://jform-designer.viafirma.com/pro/

Se podrá partir de cero, con la opción New Form, o bien partir de un formulario ya existente, con la opción Import JSON.

Maquetación del Formulario

Se ofrecen tres elemento del tipo contenedor que nos ayudarán a maquetar nuestro formulario:

  • Contenedores
  • Filas

El primero equivale a un contenedor html "Fieldset", y el segundo a una fila. Con ellos podremos agrupar todos los elementos de nuestro formulario con la apariencia deseada, teniendo en cuenta que el target principal de nuestros formularios podrá ser un dispositivo móvil, hecho por el cual el diseño realizado con JForm Designer es líquido, y podrá adaptarse de manera distinta a la maquetada según el dispositivo móvil en el que se esté visualizando.

Contenedor

Lo usaremos para agrupar de manera lógica un conjunto de elementos. El contenedor permite incluir título, y podrá tener tantas filas como se desee.

Main image

Fila

Estarán dentro de un contenedor, y en ellas insertaremos los elementos de formulario que deseemos.

Main image

Habrá que tener en cuenta el tamaño de los mismos, haciendo uso del atributo size. Por ejemplo, si deseeo incluir dos elementos en la fila, podré asignarle un tamaño de 50-50, 90-10, 10-90 o cualquier combinación que sume el 100% del ancho de la fila.

Las filas podrán ser desplazadas hacia arriba o hacia abajo hasta ajustarla en el lugar deseado, siempre dentro de un contenedor. Para ello seleccionamos la fila y usaremos los botones "Up" y "Down" habilitados en la parte superior del container.

Elementos de Formulario

Una vez tengamos definida la estructura contenedora, ya podremos insertar tantos elementos de formularios como deseemos. Para ello seleccionaremos la fila en la que deseemos insertar el elemento, y usamos el botón Add item o Remove.

Main image

Una vez añadido a la fila, podremos desplazarlo a derecha o izquierda, con los botones Right y Left, y editar sus propiedades, con el botón Edit.

Main image

Listas y Listas Anidadas

Para los elementos del tipo listas tenemos una gestión específica. Para ello, usaremos los accesos directos Edit lists y E dit nested lists.

Main image

Main image

Main image

Formulario Avanzado

Un formulario avanzado podrá contener formato de datos, validación de datos, listas relacionadas, etc. Todas estas propiedades se describen a continuación.

Email

Caja de texto que valida si el texto introducido es un email con formato correcto.

{
  "key": "email",
  "type": "text",
  "label": "Email",
  "placeHolder": "insert email",
  "size": "33",
  "validation": "email"
}

type email

Como se muestra en la imagen, el teclado muestra la @ para facilitar la introducción del correo.

Teléfono

Caja de texto que habilita el teclado númerico para facilitar al usuario la introducción de un número de telefóno.

{
  "key": "number",
  "type": "tel",
  "label": "Teléfono",
  "placeHolder": "insert phone",
  "size": "33"
}

type phone

Como se muestra en la imagen, se habilita el teclado de teléfono.

Fecha

Muestra elemento calendario.

{
  "key": "date",
  "type": "date",
  "label": "Date",
  "placeHolder": "date",
  "size": "33"
}

type date

Fecha/Hora

Muestra elemento del tipo fecha/hora.

{
  "key": "datetime",
  "type": "datetime",
  "label": "Datetime",
  "placeHolder": "date time",
  "size": "33"
}

type datetime

Hora

Muestra elemento del tipo hora.

{
  "key": "time",
  "type": "time",
  "label": "Time",
  "placeHolder": "time",
  "size": "33"
}

type time

Fecha Actual

Muestra la fecha actual del dispositivo, y no permite su edición.

{
  "key": "today",
  "type": "todayText",
  "format": "%w - %d %n %y",
  "monthNames": ["January", "February", "March", "April", "May", "June", "July", "August", "September", "October", "November", "December"],
  "dayNames": ["Sunday", "Monday", "Tuesday", "Wednesday", "Thursday", "Friday", "Saturday"]
}

Formato por defecto: "%d/%m/%y"

Posibles Valores:

  • d: Day
  • m: Month number
  • n: Month name
  • w: Day name
  • y: Full year
  • H: Hours
  • M: Minutes
  • S: Seconds
  • i: ISO date

Este elemento además permite los atributos update e increment.

{
  "key": "today",
  "type": "todayText",
  "increment":"30",
  "update":"expire_date"
}

Según el ejemplo anterior, el formulario se cargaría con la fecha actual + "30 días", y además actualizaría el valor del campo "expire_date", con la fecha de expiración del contrato, contando 30 días a partir de su formalización.

Número

Habilita el teclado númerico y sólo permite valores númericos.

{
  "key": "number",
  "type": "number",
  "label": "Number",
  "placeHolder": "insert number",
  "size": "33"
}

type number

Textarea

Habilita caja de texto para un mayor contenido que las cajas de texto del tipo input text.

La longitud permitida se define con el atributo height, y éste se mide en píxeles. Su valor por defecto será de 100, el cual no hay que confundir con el atributo size, al igual que para otros elementos, se usa para definir el tamaño del elemento en relación al formulario, y se mide en %. Por ejemplo, si se define un valor de "50%", el elemento ocupará la mitad de la pantalla disponible.

{
  "key": "textarea",
  "type": "textarea",
  "label": "Textarea",
  "size": "100",
  "height": "120",
  "placeHolder" : "This is a textarea"
}

Select (lista)

Muestra el conjunto de valores contenidos en la lista informada dentro del JSON.

{
 "key": "select1",
 "type": "select",
 "label": "Select Sample",
 "list" : "combos"
}

Lista precargada para el Select

La lista que alimentará al select del ejemplo 1 deberá definirse al principio del JSON tal y como se muestra en el siguiente ejemplo:

"lists" : {
 "combos" : ["Value 1", "Value 2", "Value 3"]
}

Checkbox

Muestra el conjunto de valores contenidos en la lista informada dentro del JSON.

{
  "key": "checkbox1",
  "type": "checkbox",
  "label": "Checkboxes",
  "list" : "checkboxes"
}

Devolvemos string de lista de los valores seleccionados separados por el separador "|"

Lista precargada para el Checbox

La lista que alimentará al checkbox anterior deberá definirse al principio del JSON tal y como se muestra en el siguiente ejemplo:

"lists" : {
 "checkboxes" : ["Value 1", "Value 2", "Value 3"]
}

Radio

Muestra el conjunto de valores contenidos en la lista informada dentro del JSON.

{
 "key": "radios1",
 "type": "radio",
 "label": "Radios",
 "list" : "radios"
}

Lista precargada para el Radio

La lista que alimentará la lista de valores del radio del ejemplo anterior deberá definirse al principio del JSON tal y como se muestra en el siguiente ejemplo:

"lists" : {
 "radios" : ["Value 1", "Value 2", "Value 3"]
}

¿Cómo definir varias listas precargadas?

Para alimentar varias listas que serán usadas en distintos elementos del formularios, y siguiendo los ejemplos anteriores, se podrán informar de la siguiente forma:

"lists" : {
 "combos" : ["Value 1", "Value 2", "Value 3"],
 "checkboxes" : ["Value 1", "Value 2", "Value 3"],
 "radios" : ["Value 1", "Value 2", "Value 3"]
}

Listas Vinculadas

Los selects pueden estar vinculados de forma que los valores mostrados en cada uno dependan de los seleccionados en un select anterior, como la típica selección de provincia y con ella se recarga el select de municipios que pertenecen a esa provincia.

Para su uso nos ayudaremos del siguiente ejemplo:

En 1er lugar definimos la lista padre:

"lists" : {
 "listaPaises" : ["España", "Colombia"]
}

En segundo lugar definimos la listas hijas, y para ello usaremos el elemento nestedLists.

"nestedLists" : {
 "listaComunidades" : {
  "España" : ["Andalucía", "Galicia", "Aragón"],
  "Colombia" : ["Atlántico", "Antioquia", "Cundinamarca"]
 }
}

Y por último definimos las listas:

"items" : [
{
 "key": "comboPaises",
 "type": "select",
 "label": "Países",
 "update": "comunidades",
 "list" : "listaPaises"
},
{
 "key": "comboComunidades",
 "type": "select",
 "label": "Comunidades",
 "nestedList" : "listaComunidades"
}]

Observar que en el segundo combo no es necesario el atributo update porque este combo no actualiza a ningún otro combo hijo. Observar también que este segundo combo se usa el atributo nestedList en lugar de list, como sí se usa en su combo padre.

Este tipo de elemento se podrá usar para incluir enlaces html para llevar al usuario a contenidos externos de la app.

{
  "key": "help",
  "type": "link",
  "text": "help",
  "href": "http://www.viafirma.com"
}

Elemento de solo lectura (disabled)

Todos los elementos permiten el atributo "disabled" para que el valor introducido sólo sea de lectura y no permita su edición.

{
  "key": "name",
  "type": "text",
  "label": "Name",
  "placeHolder": "insert name",
  "size": "33",
  "disabled": true
}

Elemento de repetición (match)

Para los items del tipo "text" se permiten el atributo "match" para indicar en la validación del formulario que el valor aquí indicado debe ser igual que el introducido en el item referenciados, usado por ejemplo en los casos "Repita su contraseña", y "Repita su email".

{
  "key": "email",
  "type": "text",
  "label": "Email",
  "placeHolder": "insert email",
  "required": true,
}
{
  "key": "emailRepeat",
  "type": "text",
  "label": "Repeat Email",
  "placeHolder": "repeat email",
  "required": true,
  "match": email
}

Validación de Datos

Todos los elementos descritos arriba, pueden incorporar la mayoría de atributos de validación descritos a continuación:

Campo Requerido
{
  "key": "name",
  "type": "text",
  "required": true
}
Validación: email

Aunque se cuenta con un elemento del tipo email, sería posible usar una validación de email para cualquier elemento de texto, por ejemplo, definir un elemento tipo text, y sobre éste aplicarle una validación de email.

{
  "key": "email",
  "type": "text",
  "validation": "email"
}

Aunque está permitido este caso de uso, se recomienda usar el tipo de elemento pensado para este propósito, es decir, type:email.

Validación con Expresión Regular

Para cualquier otro tipo de dato que se desee validar se podrá usar, de forma explícita, una expresión regular a la hora de definir el componente.

Para incluir una expresión regular como validación en cualquier componente que queramos montar en nuestro formulario lo podremos hacer tal y como se muestra en el siguiente ejemplo haciendo uso del atributo validationRegex:

{
  "key": "age",
  "type": "text",
  "validationRegex": "[0-9]+"
}

En el código anterior montamos un tipo texto para solicitar la Edad del Usuario, y en la validación usamos una expresión regular para que sólo admita valores del 0 al 9.

Validación Longitud de Campos

Se podrá validar la longitud máxima y mínima elementos del tipo text. Para ello, se usaremos maxlength y minlength en cada caso.

{
  "key": "usercode",
  "type": "text",
  "maxlength": "10",
  "minlength": "5"
}

Otros Atributos

De forma común, y con algunas excepciones descritas a continuación, todos los elementos descritos anteriormente podrán hacer uso de los siguientes atributos.

Atributo Uso
size define el % de espacio que ocupará en una fila del formulario. Por ejemplo, si maquetamos cuatro cajas de texto en una misma fila, el size para cada uno sería 25.
label nombre de la etiqueta para el elemento.
placeholder texto de ayuda que se mostrará como valor predefinido en el elemento.