Marco de aspecto para formularios adaptables y HTML5 appearance-framework-for-adaptive-and-html-forms

Los formularios (formularios adaptables y formularios HTML5) utilizan las bibliotecas de jQuery, Backbone.js y Underscore.js para el aspecto y los scripts. Los formularios también utilizan la arquitectura de los widgets de la interfaz de usuario de jQuery para todos los elementos interactivos (como campos y botones) del formulario. Esta arquitectura permite al desarrollador de formularios utilizar un completo conjunto de widgets y complementos de jQuery disponibles en Forms. También puede implementar lógica específica del formulario al capturar datos de usuarios, como restricciones de leadDigits/trailDigits o la implementación de cláusulas de imagen. Los desarrolladores de formularios pueden crear y utilizar funciones personalizadas para mejorar la experiencia de captura de datos y hacerla más fácil de usar.

Este artículo va dirigido a desarrolladores con los conocimientos adecuados de jQuery y los widgets de jQuery. Proporciona una perspectiva del marco de trabajo de aspecto visual y permite a los desarrolladores crear un aspecto alternativo para un campo de formulario.

El marco de trabajo de aspecto visual se basa en diversas opciones, eventos (activadores) y funciones para capturar las interacciones del usuario con el formulario, y responde a los cambios del modelo para informar al usuario final. Además:

  • El marco proporciona un conjunto de opciones para el aspecto de un campo. Estas opciones son pares de clave-valor y se dividen en dos categorías: opciones comunes y opciones específicas de tipo de campo.
  • El aspecto, como parte del contrato, activa un conjunto de eventos; por ejemplo, eventos de entrada y salida.
  • El aspecto es necesario para implementar un conjunto de funciones. Algunas de las funciones son comunes, mientras que otras son específicas de las funciones de tipo de campo.

Opciones comunes common-options

A continuación se muestran las opciones globales establecidas. Estas opciones están disponibles para todos los campos.

Propiedad
Descripción
name
Un identificador utilizado para especificar este objeto o evento en expresiones de scripts. Por ejemplo, esta propiedad especifica el nombre de la aplicación host.
value
El valor predeterminado del campo.
displayValue
Se muestra este valor del campo.
screenReaderText
Los lectores de pantalla utilizan este valor para narrar información sobre el campo. El formulario proporciona el valor, y es posible anularlo.
tabIndex
La posición del campo en la secuencia de tabulación del formulario. Anule tabIndex solo si desea cambiar el orden de tabulación predeterminado del formulario.
role
La función del elemento, por ejemplo, Encabezado o Tabla.
height
La altura del widget. Se especifica en píxeles.
width
La anchura del widget. Se especifica en píxeles.
access
Los controles utilizados para acceder al contenido de un objeto container, como un subformulario.
paraStyles
La propiedad para de un elemento XFA del widget.
dir
La dirección del texto. Los valores posibles son ltr (de izquierda a derecha) y rtl (de derecha a izquierda).

Aparte de estas opciones, el marco proporciona otras opciones que varían según el tipo de campo. A continuación, se muestran los detalles de las opciones específicas de los campos.

Interacción con el marco de formulario interaction-with-forms-framework

Para interactuar con el marco de formulario, un widget activa una serie de eventos para permitir que funcione el script del formulario. Si el widget no desencadena estos eventos, algunos de los scripts escritos en el formulario para ese campo no funcionan.

Eventos activados por el widget events-triggered-by-widget

Evento
Descripción
XFA_ENTER_EVENT
Este evento se activa cada vez que el campo está enfocado. Permite que el script de "entrada" se ejecute en el campo. La sintaxis para activar el evento es
(widget)._trigger(xfalib.ut.XfaUtil.prototype.XFA_ENTER_EVENT)
XFA_EXIT_EVENT
Este evento se activa cada vez que el usuario abandona el campo. Permite que el motor establezca el valor del campo y ejecute su script de "salida". La sintaxis para activar el evento es
(widget)._trigger(xfalib.ut.XfaUtil.prototype.XFA_EXIT_EVENT)
XFA_CHANGE_EVENT
Este suceso se activa para permitir que el motor ejecute el script de "cambio" escrito en el campo. La sintaxis para activar el evento es
(widget)._trigger(xfalib.ut.XfaUtil.prototype.XFA_CHANGE_EVENT)
XFA_CLICK_EVENT
Este evento se activa cada vez que se hace clic en el campo. Permite al motor ejecutar el script de "clic" escrito en el campo. La sintaxis para activar el evento es
(widget)._trigger(xfalib.ut.XfaUtil.prototype.XFA_CLICK_EVENT)

API implementadas por widget apis-implemented-by-widget

El marco de apariencia llama a algunas funciones del widget que se implementan en los widgets personalizados. El widget debe implementar las siguientes funciones:

Función
Descripción
enfoque: function()
Pone el enfoque en el campo.
clic: function()
Pone el enfoque en el campo y llama a XFA_CLICK_EVENT.

markError:function(errorMessage, errorType)

erorrMessage: cadena representación del error
errorType: cadena ("advertencia"/"error")

Nota: Aplicable solo para formularios HTML5.

Envía un mensaje de error y un tipo de error al widget. El widget muestra el error.

clearError: function()

Nota: Aplicable solo para formularios HTML5.

Se llama a esta función si se corrigen los errores en el campo. El widget oculta el error.

Opciones específicas del tipo de campo options-specific-to-type-of-field

Todos los widgets personalizados deben cumplir las especificaciones anteriores. Para utilizar las funciones de diferentes campos, el widget debe ajustarse a las directrices de ese campo en particular.

TextEdit: campo de texto textedit-text-field

Opción
Descripción
multiline
El valor es True si el campo admite la introducción de un carácter de nueva línea; en caso contrario, es False.
maxChars
El número máximo de caracteres que se pueden introducir en el campo.

limitLengthToVisibleArea

Nota: Aplicable únicamente a los formularios HTML5

Especifica el comportamiento del campo de texto cuando la anchura del texto supera la anchura del widget.

ChoiceList: DropDownList, ListBox choicelist-dropdownlist-listbox

Opción
Descripción
value
La matriz de los valores seleccionados.
items
La matriz de objetos que se van a mostrar como opciones. Cada objeto contiene dos propiedades:
save: el valor que desea guardar; display: el valor que desea mostrar.

editable

Nota: Aplicable solo para formularios HTML5.

Si el valor es True, la entrada de texto personalizado está habilitada en el widget.
displayValue
La matriz de los valores que se van a mostrar.
multiselect
El valor es True si se permiten varias selecciones; en caso contrario, es False.

API api

Función
Descripción
addItem: function(itemValues)
itemValues: el objeto que contiene el valor de visualización y guardado
{sDisplayVal: <displayValue>, sSaveVal: <save Value>}
Agrega un elemento a la lista.
deleteItem : function(nIndex)
nIndex: el índice del elemento que se va a eliminar de la lista
Elimina una opción de la lista.
clearItems: function()
Borra todas las opciones de la lista.

NumericEdit: NumericField, DecimalField numericedit-numericfield-decimalfield

Opciones
Descripción
dataType
Cadena que representa el tipo de datos del campo (entero/decimal).
leadDigits
El máximo de dígitos iniciales permitido en el número decimal.
fracDigits
El máximo de dígitos de fracción permitidos en el número decimal.
zero
La representación de cadena del cero en la configuración regional del campo.
decimal
La representación de cadena del decimal en la configuración regional del campo.

CheckButton: RadioButton, CheckBox checkbutton-radiobutton-checkbox

Opciones
Descripción
values

La matriz de valores (activado/desactivado/neutro).

Es una matriz de valores para los diferentes estados de checkButton. values[0] es el valor cuando el estado está ACTIVADO, values[1] es el valor cuando el estado está DESACTIVADO,
values[2] es el valor cuando el estado es NEUTRAL. La longitud de la matriz de valores es igual a la opción Valor de estado.

states

El número de estados permitidos.

Dos para los formularios adaptables (Activado, Desactivado) y tres para los formularios HTML5 (Activado, Desactivado, Neutro).

state

El estado actual del elemento.

Dos para los formularios adaptables (Activado, Desactivado) y tres para los formularios HTML5 (Activado, Desactivado, Neutro).

DateTimeEdit: (DateField) datetimeedit-datefield

Opción
Descripción
days
El nombre localizado de los días para ese campo.
months
El nombre localizado de los meses para ese campo.
zero
El texto localizado para el número 0.
clearText
El texto localizado para el botón Borrar.
recommendation-more-help
19ffd973-7af2-44d0-84b5-d547b0dffee2