Parámetros recibidos por las funciones de los eventos Ajax

Seguimos trabajando con Ajax en jQuery, en esta ocasión profundizando un poco en algunos de los eventos Ajax que tenemos disponibles en el framework. En concreto estamos viendo los eventos que podemos definir desde la función jQuery.get().

En este artículo veremos ejemplos interesantes que utilizarán eventos Ajax, como son error, success y complete. Pero sobre todo haremos inciso en los parámetros que podemos recibir en las funciones que escribimos para definir las acciones a realizar por cada evento, ya que a través de ellos podemos acceder a información interesante que quizás nos sea necesaria en algunos casos.

Evento ajax error(jqXHR, estado, excepción)

Como se dijo anteriormente, el evento error se produce cuando la solicitud Ajax no se pudo realizar por alguna razón. Se define por medio de una función que recibe tres parámetros. El primero de ellos es un objeto que contiene la propia solicitud Ajax que se está produciendo, el segundo es el estado de error (que puede ser simplemente "error", pero también algo como "timeout" que nos aclare mejor el tipo de error que se ha producido) y el tercero una excepción que pueda haberse lanzado.

En el siguiente ejemplo veremos un caso de uso del evento error.

var url = prompt("Dame la URL a la que quieres que acceda", "contenido-ajax.html");
var objajax = $.get(url);
objajax.error(function(o, estado, excepcion){
   alert("Error detectado: " + estado + "\nExcepcion: " + excepcion);
   o.complete(function(){alert("Solicitud completada evento cargado desde el evento de error!")});
});
objajax.complete(function(){alert("Solicitud completada")});

Como se ve, primero preguntamos al usuario, a través de una caja de "prompt", la URL a la que desea acceder y luego realizamos la solicitud Ajax de dicha URL con $.get(). Al mostrarse la caja "prompt" y el usuario poder escribir cualquier cosa, se puede colocar cualquier ruta que se desee, incluso nombres de páginas inexistentes, para que se produzca un error en la conexión Ajax.

Pero lo que queremos remarcar está justo después, que es la llamada al método error(), en la que indicamos la función a ejecutar cuando se produzca un error en la conexión. A ese método le enviamos la función a ejecutar cuando se produzca el error y vemos que se le pasan tres parámetros. Con los parámetros "estado" y "excepcion" simplemente los mostramos en una caja de alert, para poder verlos. Con el parámetro "o", que es una referencia al objeto Ajax que se está ejecutando, podemos, por hacer alguna cosa, como cargar otro evento. En este caso cargamos una función adicional al evento "complete", y digo adicional porque en la última línea de este código ya habíamos cargado algo al evento complete.

Por tanto, si se ha entendido bien, se comprobará que:

• Si la solicitud Ajax tuvo éxito, no se hace nada en concreto, pero se obtendrá un mensaje diciendo "Solicitud completada"
• Si la solicitud Ajax falló, tampoco hacemos nada en concreto, pero veremos varios mensajes. El primero para decir cuál es el texto asociado a este error y la excepción producida, en caso que haya alguna. El segundo mensaje que veremos, por último y también cuando se complete la solicitud, será el de "Solicitud completada evento cargado desde el evento de error!"

Puedes ver el ejemplo en marcha para comprobar por ti mismo ese funcionamiento.

Evento Ajax success(datos, estado, jqXHR)

El evento success, que se produce cuando la solicitud se ejecutó con éxito, tiene la posibilidad de recibir tres parámetros. El primero es la respuesta generada por la solicitud Ajax y el segundo es el estado de esta solicitud y el tercero el objeto Ajax de esta solicitud.

Es interesante el primer parámetro, donde recibimos los datos de respuesta de esta solicitud y si lo deseamos, podemos operar con ellos del mismo modo que si estuviéramos en la función que gestiona la respuesta Ajax. El segundo parámetro es simplemente un texto descriptivo del estado de la solicitud, que si ha tenido éxito será algo como "success".

Antes de ver un ejemplo, pasemos a explicar el otro evento que nos queda.

Evento Ajax complete(jqXHR, textStatus)

Este evento se lanza una vez la solicitud ha terminado (tanto en éxito como en fracaso) y se produce después de otros eventos Ajax. En él recibimos dos parámetros, el primero con una referencia al objeto Ajax que se está ejecutando y el segundo con una cadena que describe el estado de la conexión, como "error" si se produjo un problema o "success" si la solicitud fue realizada correctamente.

Veamos un ejemplo a continuación, en el que hacemos un pequeño "demo" de cómo podría funcionar un botón "me gusta".

var objajax = $.get("incrementa-me-gusta.php", {elemento: 32333});
objajax.error(function(){
   $("#gusto").append('<span class="error">Error al contabilizar el me gusta</span>');
});
objajax.success(function(respuesta,textostatus){
   $("#gusto").html("Contigo ya son " + respuesta + " personas a las que les gusta!");
   $("#gusto").addClass("gustado");
   $("#estadosuccess").html(textostatus);
});
objajax.complete(function(oa, textostatus){
   $("#estadocomplete").html(textostatus);
});

Como se puede ver, se inicia una solicitud Ajax con $.get(), pero no colocamos en la solicitud nada a realizar cuando ésta se reciba, pues más adelante definiremos qué hacer en caso que se produzca un error o en caso que se ejecute con éxito.

Con el método error() definimos el evento a ejecutarse en el caso que la consulta a la página incrementa-me-gusta.php no pueda ser realizada. En ese caso, simplemente mostramos un mensaje de error.

Con el evento success, definido por medio del método success(), definimos las acciones a realizar en caso que se ejecute la solicitud con éxito. Como se puede ver, en el evento se reciben dos parámetros, uno con la respuesta y el segundo con el texto de estado. Con la respuesta podemos hacer acciones, al igual que con el texto de estado. Ambos datos los mostramos en la página en distintos lugares.

Luego se define el evento complete, que recibe también un par de parámetros. Por un lado tenemos el objeto ajax que ha recibido la solicitud, con el que no hacemos nada. Luego tenemos el texto de estado, que simplemente lo mostramos en la página.

El ejemplo se puede ver en una página aparte.

Por el momento es todo lo que queríamos mostrar del método jQuery.get(), así que ya en el próximo artículo veremos una función parecida pero que hace las conexiones Ajax por medio de POST en vez de GET, con el objetivo final de mostrar cómo enviar formularios por Ajax con jQuery.