Como Usar la función "ajax" de jQuery

Spanish (Español) translation by Rodney Martinez (you can also view the original English article)

Ha seguido los tres tutoriales anteriores, entonces usted debería haber ganado una buena comprehensión de AJAX. En este tutorial final, concluiremos las cosas al trabajar con un ejemplo más interesado.

El Marcado

Para obtener una idea de la estructura de este ejemplo, considere el siguiente marcado:

      <section>
        <!-- content here -->
      </section>
      <main>
      	<!-- content here -->
      </main>
      <section>
      	<!-- content here -->
      </section>
      <div class="modal">
      	<!-- content here -->
      </div>
      <div class="loader">
      	<!-- content here -->
      </div>

El marcado para el elemento main se muestra debajo:

      <main>
        <h2>Popular front-end frameworks</h2>
        <p>Click each one to load details via AJAX.</p>
        <div class="boxes">
          <a href="#">Bootstrap</a>
          <a href="#">Foundation</a>
          <a href="#">UIkit</a>
          <a href="#">Semantic UI</a>
          <a href="#">Skeleton</a>
          <a href="#">Material Design Lite</a>
        </div>
      </main>

Observe los textos enlaces. Estos corresponden a diferentes estructuras front-end. Como veremos en la siguiente sección, cada vez que hacemos clic en los enlaces, una solicitud AJAX será ejecutada. Luego, el elemento con la clase de modal aparecerá y su contenido será actualizado con datos buscados desde la respuesta.

Aquí está como el elemento main luce:

Marcado Modal

El siguiente paso es examinar la estructura de nuestro modal. Aquí está el código HTML:

      <div class="modal">
        <button class="close" aria-label="Close">✕</button>
        <div class="m-content">
          <ul class="m-info">
            <li>Framework</li>
            <li></li>
            <li>Current Version</li>
            <li></li>
            <li>Number of Github Stars</li>
            <li></li>
            <li>Official Page</li>
            <li></li>
          </ul>
          <p class="m-message"></p>
        </div>
      </div>

Como puede ver, el modal contiene algunos elementos vacíos. Colocamos esos en el HTML porque sus texto cambiaran dependiendo de en cual enlace hacemos clic y la respuestas que recuperaremos.

La imagen debajo muestra como el modal inicial aparece:

Por defecto, el modal está oculto. Adicionalmente, ocultaremos el cargador. Éste aparecerá solo cuando una solicitud de AJAX se activada.

Eche un vistazo a las reglas CSS correspondientes:

      .modal {
          opacity: 0; 
      }

      .loader {
          display: none;
      }

Observe que usamos la propiedad opacity (y no la propiedad display) para ocultar el modal porque ésta propiedad pertenece a las propiedades CSS animadas. En esta forma, seremos capaces de hacer una transición de los estados del modal (por ejemplo, los estados abrir y cerrar).

Generando una respuesta JSON.

Para el propósito de éste ejemplo, elegiremos construir por nuestra cuenta la respuesta JSON. Específicamente, la respuesta esperada (por ejemplo, el archivo Demo.json) será unos objetos array. Cada objeto contendrá detalles respecto a la estructura front-end relacionada.

Además, el valor de la propiedad name coincidirá con el texto de enlace del elemento main (ver sección anterior). Con eso en mente, la estructura de la respuesta lucirá igual a algo como esto:

       [
         {
           "url": "http://getbootstrap.com/", 
           "numberOfStars": "88.260+", 
           "currentVersion": "3.3.5", 
           "name": "Bootstrap"
         }, 
         {
           "url": "http://foundation.zurb.com/", 
           "numberOfStars": "21.180+", 
           "currentVersion": "5.5.3", 
           "name": "Foundation"
         }, 
         // 4 more objects here
       ]

Nota: los valores que hemos usado para las propiedades numberOfStars y currentVersion son falsos y únicamente los utilizamos para propósitos de demostración.

Similar a los ejemplos anteriores en esta series, usaremos AJAX para solicitar un archivo estático. Sin embargo, si queremos incorporar contenido desde otro sitios (por ejempo, desde Google Maps, Flickr) deberíamos leer la documentación API y, si es necesario, aplicar por una clave API.

Además, nuestros datos meta están en el mismo servidor como la página demo. Además, evitaremos limitaciones que pueden ocurrir cuando interactuamos con servicios de terceros (ver la sección "Limitaciones de las Solicitudes de AJAX" del primer tutorial).

Implementando las Solicitudes de AJAX.

En esta sección, usaremos la función de ajax de jQuery para inicializar una solicitud AJAX. Antes de hacer eso, vamos a definir, primero, nuestras variables para almacenar los selectores jQuery usados con más frecuencia:

      var $list    = $('.m-info'),
      var $message = $('.m-message');
      var $modal   = $('.modal');
      var $loader  = $('.loader');
      var $framework;

Ahora, es el momento de examinar el código responsable para la ejecución de la solicitud:

      $('.boxes a').on('click', function(e) {
        e.preventDefault();
        
        $framework = $(this).text();
        
        $.ajax({
          url: 'Demo.json',
          dataType: 'json',
          beforeSend: function() {
              $loader.show();
          }
        }).done(successFunction)
          .fail(errorFunction)
          .always(alwaysFunction);
      });

Usted notará la sintaxis para la función de ajax luce como sigue:

1	$.ajax([settings])

El parámetro settings es una configuración objeto que conserva la información sobre nuestra solicitud. El número de propiedades que éste objeto puede tener es muy largo (alrededor de 34 propiedades). Por razones de sencillez, solamente discutiremos esos que son utilizados para esta demostración. Más específicamente:

Property	Description
url	Una cadena de caracteres que contiene la URL para la cual la solicitud es enviada.
dataType	El formato del dato de respuesta (por ejemplo, `json`, `xml`, `html`).
beforeSend	Una devolución de llamada de una función que es ejecutada antes de que enviemos la solicitud. Aquí, está función activa el código que muestra el cargador.

Antes que avancemos, vale la pena mencionar tres cosas:

También hay otra sintaxis para la función ajax:$.ajax(url[, settings])
Todas las propiedades de configuración del parámetro settings son opcionales.
El método HTTP por defecto es GET.

Método Promise

La función ajax devuelve el objeto jQuery XMLHttpRequest o jqXHR. Éste objeto implementa la interface Promise y así, éste contiene todas las propiedades, métodos y comportamientos de un Promise.

En este ejemplo, usamos los siguientes métodos Promise:

El método done es activado si la solicitud fue exitosa. Éste recibe uno o más argumentos, todos puede ser una sola función o un array de funciones. Por ejemplo, en nuestra demostración, la función succesFunction() es pasado como un argumento.

La devolución de la función (por ejemplo, succesFunction() acepta tres argumentos. Primero, los datos regresados. Segundo, una cadena categorizando el estado de la solicitud (ver el artículo anterior para los valores posibles). Por último, el objeto jqXHR.

El método fail es llamado si la solicitud falla. Éste recibe uno o más argumentos, todo puede ser un sola función o un array de funciones. Por ejemplo, en nuestra demostración, la función errorFunction() es pasado como un argumento.

La devolución de la función (por ejemplo, errorFunction() acepta tres argumentos: el objeto jqXHR, una cadena de caracteres categorizando el estado de la solicitud, y otra cadena que específica el error resultado. Este error recibe la porción textual del estado HTTP, tal como Not Found o Forbidden.

El método always es ejecutado cuando la solicitud termina, independientemente del éxito (por ejemplo, si el método done es ejecutado) o si falla (por ejemplo, si el método fail es ejecutado). De nuevo, éste recibe como un argumento una sola función o un array de funciones. Por ejemplo, en nuestra demostración, la función alwaysFunction() es pasado como un argumento.

El estado de la solicitud específica el argumento de la función. En caso de una solicitud exitosa, la devolución de llamada (por ejemplo, la función alwaysFunction() recibe el mismo argumento como devolución de llamada del método done. Por el contrario, si la solicitud falla, éste acepta el mismo argumento como una devolución de llamada del método fail.

Nota: En vez de los métodos Promise como; done, fail y always, que son utilizados en este ejemplo, igual podemos haber utilizado las funciones de devolución de llamadas; success, error y complete. Estas funciones son definidas en el parámetro settings.

Mostrando los Datos

SI la solicitud son exitosas, somos capaces de devolver el dato de respuesta. Luego, lo manipulamos hasta llenar los elementos vacíos del modal.

Considere el código para la devolución de llamada successFunction.

      function successFunction(data) {
        if (data.length > 0) {
          for (var i = 0; i < data.length; i++) {
            if ($framework === data[i].name) {
              $list.show();
              $message.hide();

              $list.find('li:nth-of-type(2)').text($framework);
              $list.find('li:nth-of-type(4)').text(data[i].currentVersion);
              $list.find('li:nth-of-type(6)').text(data[i].numberOfStars);
              $list.find('li:nth-of-type(8)').html('<a href="' + data[i].url + '" target="_blank">' + data[i].url + '</a>');
              break;
            } else {
              $list.hide();
              $message.show().text('No data received for this framework!');
            }
          }	
        } else {
          $list.hide();
          $message.text('No data received from your respose!');
        }
      }

Aunque actualizamos el contenido de nuestro modal, éste aún está oculto. Se vuelve visible y el cargador desaparece cuando la solicitud termina. Sólo entonces, la devolución alwaysFunction es ejecutada:

1	function alwaysFunction() {
2	$loader.hide();
3	$modal.addClass('active');
4	}

La clase active luce así:

      .active {
        opacity: 1;
        z-index: 10;
        transform: scale(1);  
      } 

Debajo puede ver la apariencia esperada del modal si hacemos clic sobre el texto de enlace Bootstrap.

Un pare de escenarios

Es importante entender el código que es ejecutado bajo ciertas circunstancias. Vamos a cubrir dos escenarios comunes:

El valor de la propiedad name no coincide con el texto de enlace del elemento main. Por ejemplo, vamos a supone que definimos una URL donde el valor de la propiedad name del proyecto que está relacionado a la estructura Foundation es Foundation2 en lugar de Fondation. En tal caso, si hacemos clic sobre el enlace de texto Foundation, el modal abajo aparecerá:

El dato de respuesta está vacío. Digamos, por ejemplo, que definimos una URL que apunta a un array vacío. En este caso, el modal lucirá como esto:

Manejando Errores

Así que hemos cubierto el código que se activa cuando la solicitud tiene éxito. Sin embargo, ¿qué pasa si la respuesta falla? En el caso de un solicitud no exitosa, ocultamos la lista y mostramos un mensaje personalizado.

Aquí está el código de la función failFunction() que demuestra ese comportamiento:

1	function failFunction(request, textStatus, errorThrown) {
2	$list.hide();
3	$message.text('An error occurred during your request: ' + request.status + ' ' + textStatus + ' ' + errorThrown);
4	}

Para familiarizarnos con este código, especificamos una URL que no existe. De ahí, el método fail será activado y el modal debajo se mostrará:

Nota: De nuevo, el mensaje de error podría ser diferente si usted ejecuta éste ejemplo, localmente.

Aquí está el Codepen integrado de muestra:

Please accept marketing cookies to load this content.

Conclusión

En este tutorial concluimos nuestra examinación de AJAX, desde una perspectiva de un diseñador web, ¡así que bien hecho! Espero que haya encontrado esta serie de tutoriales útiles y que usted haya aprendidos nuevas habilidades.

Como siguiente paso, lo animo a examinar las siguientes cosas:

Que se familiarice con las abreviaturas de métodos AJAX de jQuery que no han sido tratadas en este tutorial (por ejemplo; el método $.getJSON).
Implemente su propias solicitudes AJAX para acceder, ya sea; a los archivos estáticos o, incluso, a datos dinámicos que proceden de servicios de terceros (por ejemplo, de Flickr).