Lógica del widget

Hay dos formas de proporcionar lógica adicional a tus IU: a través de restricciones a los eventos y a las entradas.

Eventos

Puedes hacer que tus IU sean más dinámicas mediante la definición de las acciones de los widgets en respuesta a los eventos. Por ejemplo, el evento onClick en los widgets de los botones determina qué hacen los botones cuando se les hace clic.

La mayoría de los widgets tienen al menos tres eventos disponibles: onAttach, onDetach y onDataLoad. Algunos widgets tienen más eventos relacionados con la intención de su uso. Por ejemplo, un widget Campo de texto tiene un evento onValueChanged, pero no un evento onClick.

Usa la sección Eventos del Editor de propiedades para definir cómo responde un widget a los eventos. Haz clic en la flecha junto al nombre de un evento para abrir el cuadro de diálogo Elegir un evento. Selecciona una de las secuencias de comandos prefabricadas allí o escribe tu propia secuencia de comandos mediante un clic en Acción personalizada.

Nombre del evento Descripción
onAttach Ejecuta una secuencia de comandos cuando el widget se adjunta al DOM.
Ejemplo: un evento onAttach en el panel principal de una app podría leer una cookie para inicializar el estado cuando se carga una vista.
onDetach Ejecuta una secuencia de comandos cuando el widget se separa del DOM.
Ejemplo: un evento onDetach en el panel principal de una app podría escribir a una cookie para guardar el estado actual de una vista cuando un usuario se retira.
onDataLoad Ejecuta una secuencia de comandos cuando se carga el widget y sus datos.
Ejemplo: un evento onDataLoad en un widget de lista podría ocultar ciertas filas en el panel según los resultados de una consulta.
onClick Ejecuta una secuencia de comandos cuando el usuario hace clic en el widget. Disponible en botones, vínculos y otros widgets en los que se puede hacer clic.
Ejemplo: un evento onClick en un botón podría dirigir al usuario a una vista diferente.
onValueChange Ejecuta una secuencia de comandos cuando la propiedad value del widget cambia.
Ejemplo: un evento onValueChange en un campo de texto podría ejecutar una búsqueda en la fuente de datos del campo después de que un usuario termina de ingresar una consulta.
onValueEdit Ejecuta una secuencia de comandos cuando un usuario edita los valores del widget. A diferencia de onValueChange, este evento no se ejecuta como respuesta a vínculos ni a cambios programáticos.
Ejemplo: un evento onValueEdit en un campo de texto podría resaltar los términos coincidentes en respuesta a una consulta de búsqueda.
onValidate Ejecuta una secuencia de comandos cuando cambia el valor del widget o alguna otra secuencia de comandos activa la validación. La secuencia de comandos solo se ejecuta si el valor nuevo satisface las restricciones del widget.
Nota de validación: muestra una string vacía, null o undefined para valores válidos. Muestra una string no vacía con un mensaje de error para valores no válidos.

Valida la entrada

A menudo, es útil validar la entrada del usuario antes de guardarla en una base de datos. Por ejemplo, tu app puede necesitar que un número de teléfono proporcionado tenga la cantidad correcta de dígitos o que se completen los campos de nombre y apellido de un usuario. En App Maker, puedes usar restricciones para validar entradas o escribir tus propias secuencias de comandos de validación que se ejecutan en los eventos onValidate.

Validación con restricciones

Los widgets de campo de texto y área de texto tienen una sección Validación de datos en el Editor de propiedades. Estas restricciones se activan cuando el valor del widget cambia y puede mostrar un error si no se cumplen con las restricciones. Las restricciones aceptan valores explícitos, vinculaciones de datos o expresiones de vinculación.

Propiedad Descripción
required Cuando está habilitada, indica que se necesita una entrada.
minLength Define la longitud de caracteres mínima permitida de la string, incluidos los espacios en blanco. Los espacios en blanco iniciales o finales no se cuentan.
maxLength Define la longitud de caracteres máxima de la string, incluidos los espacios en blanco. Los espacios en blanco iniciales o finales no se cuentan.
regexp Define una expresión regular para validar la entrada del usuario. Use la biblioteca de expresión regular de JavaScript.
Ejemplo: una expresión que coincide con cualquier formato de código postal de los EE.UU.: ^\d{5}(-\d{4})?$.

Validación con eventos onValidate

El evento onValidate te permite escribir tus propias secuencias de comandos de validación. El mejor uso se da en estas situaciones:

  • Tu caso práctico es más complejo que lo que las restricciones de widget y campo pueden cubrir.
  • Tienes que proporcionar mensajes personalizados de error.
  • Tu validación depende de otros campos o widgets.

El evento onValidate funciona con restricciones, ya que solo se activa si el valor pasa las restricciones.

Ejemplo: una app de reserva de hoteles necesita permitir que los usuarios ingresen un valor entre 1 y 21 para el número de piso, pero no el 13.

Configura la restricción min length en 1, la restricción max length en 21 y, luego, verifica el número de mala suerte en el evento onValidate del widget:

  if (newValue == 13) {
    return "Please select a number with a bit more luck.";
  }

Activa la validación con el método validate

Las restricciones y las secuencias de comandos onValidate solo se activan cuando cambia el valor del widget y, a veces, eso no alcanza. Por ejemplo, si tienes un formulario con validación en cada campo, pero un usuario hace clic en Enviar sin llenar ni uno solo, puede que sus verificaciones de validación nunca se ejecuten.

Para evitar esta situación, puedes activar la validación con el método validate. Con el ejemplo anterior, podrías adjuntar el código siguiente al evento onClick del botón Enviar, si suponemos que está en el mismo panel que los campos validados:

  if (widget.parent.validate()) {
    // We passed validation! Do whatever you want here...
  }

Como alternativa, puedes validar cada widget de forma explícita:

  if (widget.parent.children.WidgetToValidate.validate()) {
    // We passed validation! Do whatever you want here...
  }

Prioridad de validación

App Maker valida los widgets en el orden siguiente:

  1. Restricciones de widgets:
    • Obligatorio
    • Máximo y mínimo de longitud y número
    • Expresión regular
  2. Evento onValidate
  3. Restricciones de propiedades vinculadas como restricciones de campo

La validación se detiene ni bien un paso determina que un valor no es válido. Por ejemplo, con la restricción required verificada, el evento onValidate nunca recibe un valor null, ya que ese valor no pasa la validación durante la verificación de restricciones.

Las propiedades vinculadas no se actualizan hasta que un valor nuevo pase la validación. Si un widget se vuelve válido después de fallar su verificación inicial, como resultado de una llamada validate(), las vinculaciones que involucren su propiedad value se actualizan de forma adecuada.