Hoy queremos compartir contigo una herramienta muy útil para agilizar el desarrollo de formularios en aplicaciones web: el componente dile-ajax-form. Este componente está pensado para crear formularios que se envían automáticamente al servidor mediante Ajax, sin necesidad de programar las conexiones HTTP manualmente. Vamos a explicarte cómo puedes usarlo, para qué sirve, con algunos ejemplos prácticos.

Antes de comenzar solo queremos mencionar que, al ser un Custom Element del estándar de Web Components, lo puedes usar en muchos contextos, como sitios web tradicionales y aplicaciones SPA, realizados con Javascript puro o frameworks frontend como React, Vue, Angular, etc. Todo ello permite reutilizar el código de tus formularios en cualquier proyecto.

En este artículo te enseñamos a envíar formularios por Ajax sin programar abordando los siguientes apartados de interés.

• ¿Qué es dile-ajax-form y para qué lo puedes usar?
• Instalación y Uso
• Requisitos del Formulario
• Convenciones asumidas por el componente
• Atributos y Propiedades
• Eventos Personalizados
• Ejemplo Práctico
• Personalización con CSS
• Conclusión

¿Qué es dile-ajax-form y para qué lo puedes usar?

El componente dile-ajax-form te permite crear formularios que se conectan al servidor y envían los datos de manera automática. Pero no solo eso, también está preparado para recibir las respuestas, mostrar posibles mensajes de error y mucho más.

Para usarlo solo necesitas definir unos atributos y estructurar el contenido del formulario dentro del slot del componente. Esta herramienta resulta útil cuando quieres que el proceso de envío de información sea automático, sin tener que escribir el código para realizar la conexión con el servidor.

Su uso es ideal para cualquier situación en la que necesites insertar o actualizar información en un servidor, como crear un nuevo usuario, modificar datos de un producto o agregar comentarios. Esto, sumado a su capacidad para mostrar errores de validación automáticamente, lo hace muy conveniente para formularios de registro o edición de recursos.

Este componete es parte del catálogo Dile Components, que mantenemos en DesarrolloWeb.com y EscuelaIT.

Instalación y Uso del trabajo con formularios Ajax

Para comenzar a trabajar con dile-ajax-form, primero necesitas instalar el paquete donde se encuentra:

npm i @dile/crud

Una vez instalado puedes importar el componente donde lo necesites usar, en tu código Javascript:

import '@dile/crud/components/ajax-form/ajax-form.js';

Un uso sencillo de dile-ajax-form lo podemos ver en el código siguiente:

<dile-ajax-form
  operation="insert"
  endpoint="http://example.com/enviar"
  actionLabel="Guardar"
>
  <demo-form id="form"></demo-form>
</dile-ajax-form>

Como puedes ver, el uso es extremadamente simple. Solo tienes que usar la etiqueta del componente  en tu código HTML y con ello consigues todo el comportamiento de envío vía Ajax de manera automática.

Requisitos del Componente de Formulario

El componente dile-ajax-form requiere que el formulario incluido en su slot tenga algunas funcionalidades básicas:

• Asignar valores a los campos del formulario.
• Obtener un objeto de datos con los valores de los campos.
• Mostrar errores de validación si los hay.

Para facilitar estas funciones, te recomendamos aplicar el mixin DileForm del paquete @dile/ui al formulario que quieras usar. Este mixin te aplica todos los métodos que el componente dile-ajax-form va a necesitar sin que tengas que programar nada.

De todos modos, si necesitas crear tus componentes de formulario sin usar el mixin DileForm, los métodos que necesitas que este componente implemente son los siguientes:

• getData(): Método para obtener un objeto con los valores de los campos del formulario.
• setData(data): Método para asignar valores a los campos del formulario a partir de un objeto.
• showErrors(errors): Método para mostrar errores de validación específicos en los campos del formulario.
• clearErrors(): Método para limpiar cualquier mensaje de error visible en el formulario.

Por supuesto, usar el mixin de formularios te quitará mucho trabajo, pero si quieres hacerlo tú manualmente puedes consultar el mixin mencionado para ver más cosas sobre los métodos que requiere.

Convenciones asumidas por el componente

El componente Dile Ajax Form asume una serie de convenciones que vienen heredadas directamente del funcionamiento de las API REST. Esto quiere decir que espera que el servidor responda con los códigos de status típicos de las conexiones HTTP que se usan en las convenciones REST.

Por ejemplo, si recibe una respuesta con status code 200 entenderá que el formulario ha podido procesarse correctamente, mostrando el correspondiente feedback positivo al usuario. Por ejemplo, si recibe un código de respuesta 400 o 422 entenderá que el formulario no ha podido procesarse y tratará de mostrar los correspondientes mensajes de error.

De todos modos, se puede incluir un adaptador tanto para configurar las solicitudes como procesar las respuestas. Estos son casos más avanzados que se encuentran detallados en la página de documentación de dile-ajax-form.

Componente basado en dile-ajax

Hablando de configuración también es importante mencionar que todas las personalizaciones de la gestión de las conexiones asíncronas de dile-ajax se pueden aplicar para ajustar el comportamiento del componente, permitiéndote así definir los detalles de las solicitudes HTTP y cómo manejar las respuestas.

Puedes leer el anterior artículo dedicado al componente dile-ajax para encontrar más información sobre este aspecto, así como consultar directamente la página de documentación de dile-ajax en el sitio de los Dile Components.

Atributos y Propiedades de dile-ajax-form

dile-ajax-form cuenta con varias propiedades que puedes ajustar para personalizar su comportamiento:

• operation: Define si el formulario es para insertar ("insert") o actualizar ("update").
• endpoint: URL del servicio web donde se enviará la información.
• actionLabel: El texto que aparecerá en el botón de envío.
• data: Objeto que contiene los datos que se enviarán al servidor.
• relatedId: Identificador del registro a editar (solo en caso de "update").
• loadOnInit: Indica si el formulario debe cargar y mostrar los datos del registro al inicializarse.
• showCancelButton: Muestra un botón de cancelar que, al ser pulsado, despacha un evento form-canceled.

Estas propiedades te permitirán adaptar el componente a las necesidades específicas de cada formulario.

También existen una serie de métodos en el componente que nos pueden resultar útiles. Te sugerimos consultarlos en la página de documentación.

Eventos Personalizados para escuchar las acciones de Ajax sobre el formulario

dile-ajax-form también despacha una serie de eventos personalizados que te serán útiles para manejar distintas situaciones. Algunos de ellos son:

• save-success: Se dispara cuando el formulario se ha guardado correctamente.
• save-error: Se dispara si hay errores al guardar los datos.
• form-canceled: Se dispara cuando se pulsa el botón de cancelar.

Estos eventos te permitirán interactuar con el resto de la aplicación, mostrando mensajes al usuario o actualizando la interfaz según sea necesario.

Consulta otros custom events y los detalles que ofrecen en el objeto evento en la documentación oficial.

Ejemplo Práctico de implementación del formulario ajax

Vamos a ver un ejemplo para entender mejor cómo usar dile-ajax-form en una aplicación real:

<dile-ajax-form
  operation="update"
  relatedId="1"
  loadOnInit
  endpoint="https://timer.escuelait.com/api/countries"
  actionLabel="Guardar"
>
  <demo-country-form id="form"></demo-country-form>
</dile-ajax-form>

En este ejemplo, estamos creando un formulario para actualizar la información de un país con el ID 1. Al cargar el componente, este consulta al servidor para obtener los datos y los muestra en el formulario.

Personalización con CSS

Puedes personalizar el estilo del formulario mediante varias propiedades CSS personalizadas. Por ejemplo:

• --dile-ajax-form-actions-margin-top: Define el margen superior del botón de acción.
• --dile-ajax-form-cancel-button-text-color: Establece el color del texto del botón de cancelar.

Estas opciones te dan flexibilidad para integrar el formulario al diseño de tu sitio web.

Conclusión

Con el componente dile-ajax-form ya no necesitas crear a mano los comportamientos Ajax sobre formularios. Puedes simplemente delegar en el componente para que te haga todo el trabajo engorroso y tedioso de lidiar con las conexiones asíncronas, mostrar errores en el formulario y muchas otras cosas.

Esperamos que esta guía te sirva para implementar formularios dinámicos con mucho menos esfuerzo y conseguir que tu código sea más sencillo y mantenible. Gracias a dile-ajax-form podrás ahorrar tiempo, al no tener que programar manualmente las conexiones HTTP, con la capacidad de personalizar el comportamiento del componente según nuestras necesidades.

Te animamos a que pruebes dile-ajax-form en tus próximos proyectos y descubras lo sencillo que puede ser crear formularios eficaces y ágiles. Si tienes feedback sobre este componente o necesitas alguna funcionalidad en especial puedes ponerte en contacto con nosotros y nos lo explicas para que lo valoremos juntos a fin de incorporarlo.