Este artículo presenta una guía completa para utilizar el componente dile-ajax en aplicaciones web, de modo que puedas implementar comportamientos Ajax de manera declarativa, sin tener que programar Javascript y lidiar con el código asíncrono con promesas o async/await.

Qué es dile-ajax

El componente dile-ajax es una herramienta que facilita la realización de conexiones HTTP asíncronas (comúnmente conocidas como solicitudes Ajax). La ventaja de este componente es que puedes trabajar de manera declarativa, sin la necesidad de escribir código JavaScript imperativo.

Entre otras cosas, el componente permite realizar solicitudes a un servidor y manejar las respuestas positivas, así como los posibles errores. Todo ello de manera sencilla a través de eventos personalizados.

Se trata de un Custom Element del estándar de Web Components, por lo que puedes usarlo en cualquier lugar donde se pueda usar Javascript. Incluso es compatible con todas librerías y frameworks habituales, como React, Angular, Vue, etc.

Este componente está basado en la librería Lit y además en otra popular librería llamada Axios. Puedes ver la página de la documentación del componente dile-ajax para una información detallada. De todos modos, en este artículo te lo vamos a explicar y ofrecer diversos ejemplos de utilidad. Este es el componente más "core" del catálogo de componentes para la creación de un CRUD automático.

Comenzaremos por explicar cómo instalar el componente y luego utilizarlo en distintos contextos que puedas aplicar en tu proyecto.

Instalación del componente de Ajax

Para empezar a usar dile-ajax en tu proyecto, debes instalarlo a través de npm:

npm i @dile/crud

Uso básico del componente

Una vez instalado, necesitas importar el componente en tu archivo JavaScript o en el archivo que contenga la lógica principal de tu aplicación.

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

Claves más importantes para el uso del componente dile-ajax

Una vez importado el componente con el correspondiente import, puedes usar dile-ajax escribiendo el elemento HTML del componente en tu página. Aquí tienes un ejemplo básico que muestra cómo configurarlo para hacer una solicitud GET a una API:

<dile-ajax
  method="get"
  url="https://jsonplaceholder.typicode.com/posts"
  @ajax-error=${this.handleErrors}
  @ajax-success=${this.handleSuccess}
></dile-ajax>

Cómo generar la solicitud Ajax

Aunque el componente esté configurado en el HTML, para que se realice la solicitud Ajax es necesario invocar manualmente el método generateRequest() que ofrece el componente. Esto lo haces directamente desde el código JavaScript de tu aplicación.

Como es un Web Component puedes usar los mismos métodos que usas en Javascript para trabajar con el DOM.

const ajaxComponent = document.querySelector('dile-ajax');
ajaxComponent.generateRequest();

Ese código accedería al primer componente dile-ajax que hay en el código HTML de la página y ejecutaría la consulta AJAX contra la URL que se ha indicado en la etiqueta del componente.

Una vez invocado este método, el componente procesará la solicitud de acuerdo con los parámetros configurados y emitirá uno de los dos eventos personalizados, dependiendo del resultado de la conexión. Existen dos eventos personalizados, uno para el éxito y otro para el caso de error.

Eventos personalizados

El componente dile-ajax utiliza dos eventos personalizados para notificar al desarrollador sobre el resultado de la solicitud HTTP:

1. ajax-success: Este evento se dispara cuando la respuesta del servidor tiene un código de estado HTTP que indica éxito (por defecto, entre 200 y 201).

Ejemplo de cómo manejar el evento en tu aplicación:

handleSuccess(event) {
 console.log('Solicitud exitosa:', event.detail);
}

2. ajax-error: Este evento se dispara cuando la respuesta del servidor devuelve un código de error HTTP (por ejemplo, 400, 404, 500, etc.).

Ejemplo de manejo del evento de error:

handleErrors(event) {
 console.error('Error en la solicitud:', event.detail);
}

Propiedades del componente

Ahora vamos a ver con mayor detalle las propiedades que tenemos disponibles en el componente dile-ajax. El componente dile-ajax es muy flexible y se puede personalizar mediante el uso de atributos que configuran sus propiedades principales:

• method: Define el método HTTP de la solicitud. Los valores permitidos son: "get", "post", "put", "delete", "patch". Dependiendo del tipo de operación que necesites realizar en el servidor, ajusta este valor.

• data: Es un objeto que contiene los datos que se enviarán al servidor. En solicitudes GET, estos datos se adjuntan como parámetros en la URL. En solicitudes POST, PUT, PATCH, y DELETE, los datos se envían en el cuerpo de la solicitud.

<dile-ajax method="post" url="api/users" .data=${{ name: 'Juan', age: 30 }}></dile-ajax>

• url: La URL a la que se realizará la solicitud. Debe ser una cadena de texto válida con el endpoint del servidor.

• statusSuccessCodes: Una lista de códigos de estado HTTP que el componente considera como exitosos. Por defecto, incluye [200, 201], pero puedes modificarla según las necesidades de tu API.

• language: El idioma de los mensajes de retroalimentación que el componente maneja. Los valores permitidos son 'en' para inglés y 'es' para español. Si no se define, el componente utilizará 'en' por defecto.

Métodos del componente

El método principal que debes utilizar es:

• generateRequest(): Este método es el que efectivamente ejecuta la solicitud Ajax configurada en el componente. No se realiza automáticamente al definir el componente en el HTML, por lo que deberás llamarlo desde tu lógica de JavaScript cuando desees ejecutar la solicitud.

  Ejemplo de uso:

const ajax = this.shadowRoot.querySelector('dile-ajax');
ajax.generateRequest();

Ejemplo completo de implementación

A continuación, te mostramos un ejemplo completo que incluye la definición del componente, su configuración para realizar una solicitud GET, y el manejo de los eventos ajax-success y ajax-error. Primero vamos a ver un ejemplo en el que solamente usamos Javascript, aunque lo normal es que acabes usando este componente en proyectos frontend con librerías que trabajen con vistas y enlaces de datos como Lit, Reac, etc.

Primero tendrás que introducir un código como este en tu HTML.

  <dile-ajax
    id="elajax"
    method="get"
    url="https://jsonplaceholder.typicode.com/todos"
  ></dile-ajax>

Luego tendrás que definir un Javascript que podría ser como este:

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

document.addEventListener('DOMContentLoaded', function() {

  const elajax = document.getElementById('elajax');

  elajax.addEventListener('ajax-success', function(e) {
    console.log(e.detail);
    const todos = e.detail;
    todos.forEach(todo => {
      const paragraph = document.createElement('p');
      paragraph.innerText = `${todo.id}: ${todo.title}`;
      document.body.appendChild(paragraph);
    });
  });
  elajax.addEventListener('ajax-error', function(e) {
    console.log('error', e.detail);
    const paragraph = document.createElement('p');
    paragraph.innerText = `${e.detail.message}`;
    document.body.appendChild(paragraph);
  });

  elajax.generateRequest();

});

En el código anterior hemos realizado primero una importación del componente.

Ten en cuenta que el script javascript tiene que tener el type="module" para que funcionen los imports. Además, cuando hacemos imports con los nombres de los packages de npm necesitas alguna herramienta como Vite o Webpack para que haga las traducciones de esos imports a las rutas donde están los archivos en la carpeta node_modules. Todo esto es conocimiento básico del desarrollo frontend que esperamos que poseas, pero si no es así encuentras mucha información en desarrolloweb para poder aprender.

Luego tenemos un evento DOMContentLoaded para ejecutar acciones cuando el DOM está disponible. Entonces realizamos los procesos para la definición de los manejadores de eventos mediante Javascript nativo y el generateRequest() para realizar la conexión propiamente dicha.

Ejemplo en un componente Lit

El código anterior, aunque es una buena propuesta para entender que los Web Components son Javascript y como tal puedes usar los mismos métodos de trabajo con el DOM para ejecutar sus comportamientos, generalmente cambiará algo en la mayoría de las ocasiones, dado que en los proyectos frontend actuales generalmente trabajarás con alguna librería de vistas. Es por ello que ahora te mostramos un ejemplo completo de uso de dile-ajax en un componente Lit.

Esta podría ser una posible organización del código en un componente Lit, donde tenemos como puntos positivos una definición más sencilla de los manejadores de eventos personalizados del componente dile-ajax, junto con la posibilidad de usar templates con los que es mucho más fácil trabajar con los datos recibidos por la solicitud, de manera declarativa.

<!DOCTYPE html>
<html lang="es">

<head>
  <meta charset="UTF-8">
  <meta name="viewport" content="width=device-width, initial-scale=1.0">
  <title>Probando dile-ajax</title>
</head>

<body>

  <my-app></my-app>

  <script type="module">
    import { LitElement, html } from 'lit';
    import '@dile/crud/components/ajax/ajax.js';

    class MyApp extends LitElement {
      firstUpdated() {
        const ajaxComponent = this.shadowRoot.getElementById('ajaxComponent');
        ajaxComponent.generateRequest();
      }

      static get properties() {
        return {
          todos: { type: Array }
        };
      }

      constructor() {
        super();
        this.todos = [];
      }

      render() {
        return html`
        <dile-ajax
          id="ajaxComponent"
          method="get"
          url="https://jsonplaceholder.typicode.com/posts"
          @ajax-success=${this.handleSuccess}
          @ajax-error=${this.handleErrors}
      ></dile-ajax>
      <h2>Tareas</h2>
      <ul>
        ${this.todos.map(todo => html`
          <li>
            <b>${todo.id}</b>:
            ${todo.title}
          </li>
        `)}
      `
      }
      handleSuccess(event) {
        const data = event.detail;
        console.log('Datos recibidos:', data);
        this.todos = event.detail;
      }

      handleErrors(event) {
        const error = event.detail;
        console.error('Error en la solicitud:', error);
      }
    }

    customElements.define('my-app', MyApp);
  </script>


</body>
</html>

Personalizar la solicitud HTTP en dile-ajax

El componente dile-ajax utiliza Axios por abajo para realizar las solicitudes al servidor. Esto significa que toda la gestión de la configuración de Axios es manejada automáticamente por el propio componente, lo que simplifica las solicitudes en la mayoría de los casos.

Sin embargo, es posible que en aplicaciones más complejas o con requisitos específicos, necesites personalizar algunos aspectos del comportamiento de Axios. A continuación te explicamos cómo puedes hacerlo.

¿Cuándo es necesario personalizar Axios?

En aplicaciones simples, es posible que no necesites realizar ninguna configuración adicional en las solicitudes HTTP que haces con dile-ajax. El componente ya ofrece una configuración predeterminada que cubre los casos más comunes. Sin embargo, en proyectos donde se requiere un mayor control sobre las solicitudes, como agregar encabezados personalizados, enviar datos de autenticación, etc. es muy probable que quieras ajustar la instancia de Axios que utiliza dile-ajax.

Configuración de Axios

Si quieres personalizar tu instancia de Axios, porque tienes un conocimiento sólido de la librería, o ya la estás usando en tu proyecto, simplemente tienes que asignar una variable global axios en tu página.

window.axios = myAxiosInstance

Si quieres además crear otras personalizaciones de Axios el mismo package donde está dile-ajax ofrece un creador de configuraciones personalizadas que cubren los casos más comunes. Para más información sobre este aspecto te sugiero consultar la documentación completa de la clase dedicada a la generación de configuraciones Axios personalizadas que ofrece dile-ajax.

Vídeo de dile-ajax

Ahora te dejamos con un vídeo que explica cómo puedes usar dile-ajax en un proyecto frontend, desde cero y paso a paso. Esperamos que te pueda aclarar algunos puntos adicionales para poder implementar este componente de trabajo con Ajax.

Conclusión

El componente dile-ajax es una solución eficiente para realizar solicitudes HTTP asíncronas en aplicaciones web frontend. Podemos usarlo con Javascript nativo, pero donde aporta su mejor cara es cuando trabajamos desde otros componentes Lit o componentes de otros frameworks. Su naturaleza declarativa, junto con la gestión de eventos personalizados para las respuestas del servidor, lo convierte en una herramienta muy útil para los desarrolladores que buscan simplificar la interacción con APIs. Al usar dile-ajax, puedes hacer solicitudes HTTP de manera fácil, manejar respuestas y errores, y mantener tu código limpio y y sencillo.